Adds methods for cross-type links

[edhzsz]

As discussed in Issue #52
This pull request allows to create links to other types in the assembly using markdown style links with the name of a type. It can be full name or simple name:

module MyModule =
  type MyType = int

  /// This returns a [MyModule.MyType].
  let f x :MyType = x * 2

  /// This returns a [MyType].
  let f x :MyType = x * 2

Work in progress. Please review.

TODO:

• Support cross-type links using Markdown links and full name of the type
• Support cross-type links using Markdown links and simple name of the type
• Support cross-type links when inline code (using backticks) contains only the (simple or full) name of a type
• Add examples of usage of cross-type links to the metadata.fsx docs
• Add warning when a link cannot be resolved due to duplicate possibilities.

[tpetricek]

This is looking great! I like the trick where you're finding all links and add the definitions for them, that's clever :-).

I wonder what would be the most common uses for this. I had a quick look at some of the Deedle docs and that is mostly using the backtick (inline code) when referring to other functions/types/modules. So obviously, getting it to work for Deedle would be one nice thing.

I'm not sure what other features would make the most sense. I'll ask for feedback on Twitter :)

[edhzsz]

I haven't saw any feedback, so I continued with my implementation. 😄

I have added the possibility to link using only the type simple name instead of the full type name.
This causes a problem when there are types with duplicated simple names. I decided to leave the link as undefined in this case.

I am not sure if links to external types should be supported. I believe they should not.

With this, I am near to be able to create links when backtick is used. I will restrict myself to types and modules in this pull request and I will try to add links to functions later.

[matthid]

Looks good to me. Just one note: If you cannot resolve the name due to duplicate possibilities it might make sense to notify the user with a logging entry (warning?).
Ideally we use the same symbol the compiler would use in the same context, which is not possible :(.

I am not sure if links to external types should be supported. I believe they should not.

In <see cref='s' /> links I decided to link against MSDN if the link could not be resolved internally, which is what Visual Studio is doing when pressing F1? For simple names I tend to agree with you though, as it is quite difficult to find the correct type (without the information a compiler has at this position).

Again very nice! I think I will update the cref resolution to use this as well once you are finished. Thanks.

Thinking about this further: Maybe it would make sense in the future to generate the reference documentation before the simple markdown files. This should enable us to replace links in the regular documentation as well (Of course not part of this PR, but a lot of this code could be reused to make this happen)

[edhzsz]

Finally had time to continue working on this. Basically I just finished the implementation.
I am adding the docs and I will add the warning when the link could not be created due to duplicated possibilities.
I also believe that it would be better to generate the links earlier in the process, I will finish this and I will give it a try.

[edhzsz]

Good to go!... I hope. 😄

[matthid]

Released in https://www.nuget.org/packages/FSharp.Formatting/2.11.1-alpha1