C# support (suggestion)

[matthid]

This is a suggestion on how to add C# support.

While now C# assemblies will now be processed we still have the following problems:

• Methods/Constructors will not be shown in the final documentation page, we need support in FSharp.Compiler.Service (maybe we should have this pull request open until the FSharp.Compiler.Service is fixed, as it is not as usefull until this is fixed, if you want to use this you can use matthid/FSharp.Compiler.Service@c5dfd4d)
• Exception when there are extension methods (Reference documentation generation with CSharp Extension methods fails #201)
• Obviously line references are not working

The other commits add support for Assembly information in a type (you can add something like: Defined in Assembly "Other.dll" to you type template), see https://github.com/matthid/RazorEngine/blob/develop/doc/templates/reference/type.cshtml#L32. Now the namespaces are sorted (when you have multiple assemblies).

[Vidarls]

Great work @matthid 👍
(Only wish I'd spent 2 min checking the pending pull requests before doing my own attempt at a fix today. Yours is way better than mine by the way 😄 )

[matthid]

Thanks! Yeah I already used it in several projects before I did the pull request. It all works fine when used with a modified FSharp.Compiler.Service.dll.

[forki]

Good work! Is this already fixed in FCS? Where is the pull request?
On Oct 5, 2014 3:47 PM, "matthid" [email protected] wrote:

This is a suggestion on how to add C# support.

While now C# assemblies will now be processed we still have the following
problems:

• Methods/Constructors will not be shown in the final documentation
  page, we need support in FSharp.Compiler.Service (maybe we should have this
  pull request open until the FSharp.Compiler.Service is fixed, as it is not
  as usefull until this is fixed, if you want to use this you can use
  matthid/FSharp.Compiler.Service@c5dfd4d
  matthid/FSharp.Compiler.Service@c5dfd4d
  )
• Exception when there are extension methods (Reference documentation generation with CSharp Extension methods fails #201
  Reference documentation generation with CSharp Extension methods fails #201)
• Obviously line references are not working

The other commits add support for Assembly information in a type (you can
add something like: Defined in Assembly "Other.dll" to you type template),
see
https://github.com/matthid/RazorEngine/blob/develop/doc/templates/reference/type.cshtml#L32.

Now the namespaces are sorted (when you have multiple assemblies).

You can merge this Pull Request by running

git pull https://github.com/matthid/FSharp.Formatting csharp_support

Or view, comment on, or merge it at:

#208
Commit Summary

• added support for C# fixes API generation fails when attempting to parse <Module> type in C# assemblies #180.
• Support for C# methods and constructors (at least with patched
  FSharp.Compiler.Service commit, c5dfd4dd488f6dcd1024b0ed2b564ce9d2d414fa).
• add enclosing assembly info to type and method (could be an
  important part in the docs).
• order namespaces in AssemblyGroup
• handle possible exceptions while processing members.

File Changes

• M src/FSharp.MetadataFormat/Main.fs
  https://github.com/tpetricek/FSharp.Formatting/pull/208/files#diff-0
  (102)

Patch Links:

• https://github.com/tpetricek/FSharp.Formatting/pull/208.patch
• https://github.com/tpetricek/FSharp.Formatting/pull/208.diff

—
Reply to this email directly or view it on GitHub
#208.

[matthid]

There is none, because I still don't know what I have actually done with my changes of if they are a good idea generally :)

[forki]

Ok please send it anyway and mark it as WIP. Don and others can help and
comment.
On Oct 6, 2014 12:02 PM, "matthid" [email protected] wrote:

There is none, because I still don't know what I have actually done with
my changes of if they are a good idea generally :)

—
Reply to this email directly or view it on GitHub
#208 (comment)
.

[matthid]

See fsharp/fsharp-compiler-docs#229.

[Vidarls]

Is there any way to just get in the simple path fix without waiting for the Compiler services?
Right now the documentation generating is completely crashing because of the path thingy.
Better to have "empty" docs than having the build crashing.

just change line 151 of the Main.fs in Metadataformat to this:

 let nice = name.Replace(".", "-").Replace("`", "-").Replace("<", "").Replace(">", "")

And the crashing goes away.

We can then continue to work on improving the c# docs

[forki]

@Vidarls please send PR. will merge and release asap.

[matthid]

Note that the fist commit does exactly that and it even filters all invalid characters so this error can't happen again. But note that the rest of the first commit is not suited for a merge... You should add && (typ.IsClass || typ.IsInterface) at line 668.
(Because apparently .FullName can throw exceptions, which properties should not do)

[forki]

I prefer a separate pull request. Since CI and stuff...

[forki]

Ok?

[matthid]

Note also that there is actually one reason to merge all commits immediately: This way if someone wants to use C# support he only has to bundle the fixed FCS.dll instead of bundling FSharp.Formatting as well. @Vidarls are you working on it or should I split it?

[Vidarls]

I have a pull req almost ready

[devboy]

I also encountered an issue when trying to generate documentation for a C# dll that contained events:

Version:

FSharp.Formatting (2.4.36)
      FSharp.Compiler.Service (0.0.67)
      Microsoft.AspNet.Razor (2.0.30506.0)
      RazorEngine (3.3.0)

Microsoft.FSharp.Compiler.ErrorLogger+ReportedError: The event '_productsLoadedEvent' has a non-standard type. If this e
vent is declared in another CLI language, you may need to access this event using the explicit add__productsLoadedEvent
and remove__productsLoadedEvent methods for the event. If this event is declared in F#, make the type of the event an in
stantiation of either 'IDelegateEvent<_>' or 'IEvent<_,_>'.
   at Microsoft.FSharp.Compiler.ErrorLogger.ErrorLoggerExtensions.ErrorLogger.Error[b](ErrorLogger x, Exception exn) in
C:\GitHub\fsharp\FSharp.Compiler.Service\src\fsharp\ErrorLogger.fs:line 321
   at Microsoft.FSharp.Compiler.Infos.ArgsTypOfEventInfo(InfoReader infoReader, range m, AccessorDomain ad, EventInfo ei
nfo) in C:\GitHub\fsharp\FSharp.Compiler.Service\src\fsharp\infos.fs:line 3612
   at Microsoft.FSharp.Compiler.Infos.PropTypOfEventInfo(InfoReader infoReader, range m, AccessorDomain ad, EventInfo ei
nfo) in C:\GitHub\fsharp\FSharp.Compiler.Service\src\fsharp\infos.fs:line 3623
   at Microsoft.FSharp.Compiler.SourceCodeServices.FSharpMemberFunctionOrValue.get_ReturnParameter() in C:\GitHub\fsharp
\FSharp.Compiler.Service\src\fsharp\vs\Symbols.fs:line 1339
   at FSharp.MetadataFormat.ValueReader.readMemberOrVal(ReadingContext ctx, FSharpMemberFunctionOrValue v) in D:\code\FS
harp.Formatting\src\FSharp.MetadataFormat\Main.fs:line 338
   at [email protected](String cat, IDictionary`2 _arg1, Comment comment) in D:\code
\FSharp.Formatting\src\FSharp.MetadataFormat\Main.fs:line 596
   at FSharp.MetadataFormat.Reader.readCommentsInto[a](ReadingContext ctx, String xmlDoc, FSharpFunc`2 f) in D:\code\FSh
arp.Formatting\src\FSharp.MetadataFormat\Main.fs:line 581
   at FSharp.MetadataFormat.Reader.tryReadMember(ReadingContext ctx, MemberKind kind, FSharpMemberFunctionOrValue memb)
in D:\code\FSharp.Formatting\src\FSharp.MetadataFormat\Main.fs:line 595
   at [email protected](FSharpMemberFunctionOrValue memb) in D:\code\FSharp.Formatt
ing\src\FSharp.MetadataFormat\Main.fs:line 602
   at Microsoft.FSharp.Collections.IEnumerator.choose@154.System-Collections-IEnumerator-MoveNext()
   at Microsoft.FSharp.Collections.SeqModule.ToList[T](IEnumerable`1 source)
   at [email protected](String cat, IDictionary`2 cmds, Comment comment) in D:\code\FShar
p.Formatting\src\FSharp.MetadataFormat\Main.fs:line 710
   at FSharp.MetadataFormat.Reader.readCommentsInto[a](ReadingContext ctx, String xmlDoc, FSharpFunc`2 f) in D:\code\FSh
arp.Formatting\src\FSharp.MetadataFormat\Main.fs:line 581
   at FSharp.MetadataFormat.Reader.readType(ReadingContext ctx, FSharpEntity typ) in D:\code\FSharp.Formatting\src\FShar
p.MetadataFormat\Main.fs:line 673
   at [email protected](ReadingContext ctx, FSharpEntity typ) in D:\code\FSh
arp.Formatting\src\FSharp.MetadataFormat\Main.fs:line 668
   at Microsoft.FSharp.Collections.IEnumerator.choose@154.System-Collections-IEnumerator-MoveNext()
   at Microsoft.FSharp.Collections.SeqModule.ToList[T](IEnumerable`1 source)
   at FSharp.MetadataFormat.Reader.readModulesAndTypes(ReadingContext ctx, IEnumerable`1 entities) in D:\code\FSharp.For
matting\src\FSharp.MetadataFormat\Main.fs:line 669
   at FSharp.MetadataFormat.Reader.readNamespace(ReadingContext ctx, String ns, IEnumerable`1 entities) in D:\code\FShar
p.Formatting\src\FSharp.MetadataFormat\Main.fs:line 744
   at [email protected](Tuple`2 tupledArg) in D:\code\FSharp.Formatting\src\FSharp.Meta
dataFormat\Main.fs:line 768
   at [email protected](b& )
   at Microsoft.FSharp.Collections.IEnumerator.MapEnumerator`1.System-Collections-IEnumerator-MoveNext()
   at Microsoft.FSharp.Collections.SeqModule.ToList[T](IEnumerable`1 source)
   at FSharp.MetadataFormat.Reader.readAssembly(FSharpAssembly assembly, Boolean publicOnly, String xmlFile, FSharpOptio
n`1 sourceFolderRepo, FSharpFunc`2 urlRangeHighlight, Boolean markDownComments) in D:\code\FSharp.Formatting\src\FSharp.
MetadataFormat\Main.fs:line 763
   at <StartupCode$FSharp-MetadataFormat>[email protected](IEnumerable`1& next) in D:\code\FSharp.For
matting\src\FSharp.MetadataFormat\Main.fs:line 0
   at Microsoft.FSharp.Core.CompilerServices.GeneratedSequenceBase`1.MoveNextImpl()
   at Microsoft.FSharp.Core.CompilerServices.GeneratedSequenceBase`1.System-Collections-IEnumerator-MoveNext()
   at Microsoft.FSharp.Collections.SeqModule.ToList[T](IEnumerable`1 source)
   at FSharp.MetadataFormat.MetadataFormat.Generate(FSharpList`1 dllFiles, String outDir, IEnumerable`1 layoutRoots, FSh
arpOption`1 parameters, FSharpOption`1 namespaceTemplate, FSharpOption`1 moduleTemplate, FSharpOption`1 typeTemplate, FS
harpOption`1 xmlFile, FSharpOption`1 sourceRepo, FSharpOption`1 sourceFolder, FSharpOption`1 publicOnly, FSharpOption`1
libDirs, FSharpOption`1 otherFlags, FSharpOption`1 markDownComments, FSharpOption`1 urlRangeHighlight) in D:\code\FSharp
.Formatting\src\FSharp.MetadataFormat\Main.fs:line 875
   at <StartupCode$FSI_0002>.$FSI_0002.main@() in X:\wooga\Wooga.InAppPurchase.Unity3D.T\docs\tools\generate.fsx:line 93

[dsyme]

That should be recorded as an FCS issue (and use a try/with as a workaround for now)

[devboy]

@dsyme sorry for the late reply. Where & and how should I report this issue for the Compiler Services?
I just recently started looking into .NET/C#/F#/Mono/CLR and need some pointers ;)

[matthid]

Note: I updated this branch to exclude everything that has been done and merged by @Vidarls. Now it can be merged again.

[tpetricek]

Thanks for the update!

I merged this - the only change I did is that I manually incorporated the change from @ovatsus in #223 where he also filters out members that have the IsOverrideOrExplicitMember flag set. I hope that's OK for C# too.

Are you using this for some specific C# project? It would be great to have a test for this - I guess we could add a sample C# project to the tests, or we could just include a DLL+XML of a project that you're using and check that it works for that one.

[matthid]

I think I saw a flag somewhere to include documentation for private members? In this case one would assume that those are included, but it will probably not matter that much.

Yes I used this for several projects.. A public one is RazorEngine. However until FCS (fsharp/fsharp-compiler-docs#229) is fixed you do not get that much documentation to test :). The xml file is already included in the nuget package so .dll and .xml files are already here.

[dsyme]

I've taken a look at this. You should not really be calling ReturnParameter on a non-standard C# Event at all - this gets the type of an event if it is considereed to be like an IEvent-typed property by the F# type system. But some events are "non-standard" and can't be given a good type as a property, and these must be called using add_XYZ and remove_XYZ.

That said, I'm adjusting FCS to still give a ReturnParameter with the delegate type of the event in this case. I'm also adding properties EventIsStandard, EventAddMethod and EventRemoveMethod to allow you to be more fine-grained if you need to be.