[Question] What needs to be done to improve support for reference docs from C# assemblies

[Vidarls]

(This is a follow up of the discussion in #217)

The current state of docs generated from C# assemblies is rather lacking.

While Fsharp.Formatting no longer crashers, it does not generate a lot of useful docs either

Earlier discussions seems to have ended with FCS being responsible for most of what is missing.
Adding to that, FSharp.Formatting is currently pinned to an older release of FCS due to some issues I can't quite remember.

I would very much like to help push the cross language support of FSharp.Formatting forward, but I need some guidance and pointers as to where I should start. Particularly if where I should start is by doing something to FCS.

As an alternative to the FCS route, we could go the complete separate route and explore whether using Roslyn for C# assemblies is a better way than trying to bend FCS into C# land.

I like what FSharp.Formatting can do with F# code, and I've yet to find a tool that provides the same nice result and ease of use, so I'd very much like to see good C# support aswell.

[Vidarls]

Looked into Roslyn a bit today. Unfortunately it has a dependency on Msbuild v 14, and I could not get this to work. Looks like we have to wait for the next .net version before that is an option. On the other hand, actually using it to get info about types and members, with line numbers and all sorts of fun stuff looks quite straight forward. I believe we can probably be able to do something like the literal programming we have for F# using it. (Some time in the future).

Currently I believe the only way forward is one of two:

1. Figure out if FCS can (and want to) provide what we need to get metadata info of C# projects, and help out in FCS to make this happen. Unfortunately there seems to be little interrest from those active and knowledgable in FCS to give feedback to such requests (Missing metadata from referenced non-F# assemblies  fsharp/fsharp-compiler-docs#235 and Metadata of C# (and other) Assemblies. fsharp/fsharp-compiler-docs#229 )
2. Make some separate Generic functionality that uses normal .net reflection to get Metadata and create what documentation we can from that. Even better if we can somehow detect if an assembly is F# and use the good FCS powered engine for those assemblies, and fall back to generic reflection based engine for C# assemblies.

[matthid]

I agree: Full C# support would be a nice boost for FSharp.Formatting.

I looked into Roslyn as well (as a faster backend for RazorEngine) and by using the NuGet package (Microsoft.CodeAnalysis) everything seemed to work fine. Did you try that?
The downside is that this nuget package is net45 only (and FSharp.Formatting wants to be net40 compatible for some reason).

But I still think the best way forward is to try to improve FCS whenever possible. On the other side I have to agree that FCS seems to be moving rather slowly :(.

Can we get line numbers from reflection?
My vote is against reflection: The longer term solution is definitely roslyn (if FCS can't provide the features we need for some reason). Besides that it looks like a short term solution with limited use (what is the benefit to a modified FSC.dll?) that will be eventually replaced by either roslyn or FCS functionality.

Besides that you can already generate a very sophisticated documentation out of C# code by using a modified FSC.dll: For example https://antaris.github.io/RazorEngine/references.
So I don't see the need for huge code rework, when the actual fix (fsharp/fsharp-compiler-docs#229) seems to be very small. The only reason I can see is the line feature (again only if FCS cannot provide this).

The next days I will look into the issue open at FCS and see if there are ways to push that forward...

TLDR: I agree completly with 1. but would rather look into roslyn than reflection (even when it is still beta).

[Vidarls]

I did use the Roslyn nuget packages (Microsoft.CodeAnalysis) But there was a runtime dependency on MsBuild v14 (looks to be introduced recently), that I could not satisfy without installing the visual studio preview version.

Looking at your PR for FCS, it seems like a minor change to get in, and the results you link to looks good.

[matthid]

My FSharp.Compiler.Service changes just got merged and there is already a nuget release, so FSharp.Formatting should now work fine on C# projects (without line numbers).

[Vidarls]

Excellent :)

[Vidarls]

It seems to be working really good. Thanks @matthid 😄

Closing this issue for now. We can create a new one if our amibtions increase or problems should surface.