API generation fails when attempting to parse <Module> type in C# assemblies

[eiriktsarpalis]

For whatever reason, the library attempts to generate documentation for the <Module> type. This causes a failure, since the ouput file contains invalid characters.

This is the type record that caused the failure:

{Name = "<Module>";
 UrlName = "global-<module>";
 Comment = {Blurb = "";
            FullText = "";
            Sections = [];};
 UnionCases = [];
 RecordFields = [];
 StaticParameters = [];
 AllMembers = [];
 Constructors = [];
 InstanceMembers = [];
 StaticMembers = [];}

and here is the complete stacktrace:

System.AggregateException: One or more errors occurred. ---> System.ArgumentExce
ption: Illegal characters in path.
   at System.IO.Path.CheckInvalidPathChars(String path, Boolean checkAdditional)

   at System.IO.Path.Combine(String path1, String path2)
   at <StartupCode$FSharp-MetadataFormat>.$Main.Generate@922-5.Invoke(Type typ,
ParallelLoopState _arg2, RazorRender razor) in c:\Tomas\Public\FSharp.Formatting
\src\FSharp.MetadataFormat\Main.fs:line 926
   at System.Threading.Tasks.Parallel.<>c__DisplayClass32`2.<PartitionerForEachW
orker>b__30()
   at System.Threading.Tasks.Task.InnerInvoke()
   at System.Threading.Tasks.Task.InnerInvokeWithArg(Task childTask)
   at System.Threading.Tasks.Task.<>c__DisplayClass11.<ExecuteSelfReplicating>b_
_10(Object param0)
   --- End of inner exception stack trace ---
   at System.Threading.Tasks.Task.ThrowIfExceptional(Boolean includeTaskCanceled
Exceptions)
   at System.Threading.Tasks.Task.Wait(Int32 millisecondsTimeout, CancellationTo
ken cancellationToken)
   at System.Threading.Tasks.Task.Wait()
   at System.Threading.Tasks.Parallel.PartitionerForEachWorker[TSource,TLocal](P
artitioner`1 source, ParallelOptions parallelOptions, Action`1 simpleBody, Actio
n`2 bodyWithState, Action`3 bodyWithStateAndIndex, Func`4 bodyWithStateAndLocal,
 Func`5 bodyWithEverything, Func`1 localInit, Action`1 localFinally)
   at System.Threading.Tasks.Parallel.ForEachWorker[TSource,TLocal](IEnumerable`
1 source, ParallelOptions parallelOptions, Action`1 body, Action`2 bodyWithState
, Action`3 bodyWithStateAndIndex, Func`4 bodyWithStateAndLocal, Func`5 bodyWithE
verything, Func`1 localInit, Action`1 localFinally)
   at System.Threading.Tasks.Parallel.ForEach[TSource,TLocal](IEnumerable`1 sour
ce, Func`1 localInit, Func`4 body, Action`1 localFinally)
   at FSharp.MetadataFormat.Parallel.pfor[TSource,TLocal](IEnumerable`1 input, F
SharpFunc`2 localInit, FSharpFunc`2 body) in c:\Tomas\Public\FSharp.Formatting\s
rc\Common\Razor.fs:line 18
   at FSharp.MetadataFormat.MetadataFormat.Generate(FSharpList`1 dllFiles, Strin
g outDir, IEnumerable`1 layoutRoots, FSharpOption`1 parameters, FSharpOption`1 n
amespaceTemplate, FSharpOption`1 moduleTemplate, FSharpOption`1 typeTemplate, FS
harpOption`1 xmlFile, FSharpOption`1 sourceRepo, FSharpOption`1 sourceFolder, FS
harpOption`1 publicOnly, FSharpOption`1 libDirs, FSharpOption`1 otherFlags, FSha
rpOption`1 markDownComments, FSharpOption`1 urlRangeHighlight) in c:\Tomas\Publi
c\FSharp.Formatting\src\FSharp.MetadataFormat\Main.fs:line 922
   at <StartupCode$FSI_0002>.$FSI_0002.main@() in c:\Development\VS 2013\FsPickl
er\docs\tools\generate.fsx:line 94
---> (Inner Exception #0) System.ArgumentException: Illegal characters in path.
   at System.IO.Path.CheckInvalidPathChars(String path, Boolean checkAdditional)

   at System.IO.Path.Combine(String path1, String path2)
   at <StartupCode$FSharp-MetadataFormat>.$Main.Generate@922-5.Invoke(Type typ,
ParallelLoopState _arg2, RazorRender razor) in c:\Tomas\Public\FSharp.Formatting
\src\FSharp.MetadataFormat\Main.fs:line 926
   at System.Threading.Tasks.Parallel.<>c__DisplayClass32`2.<PartitionerForEachW
orker>b__30()
   at System.Threading.Tasks.Task.InnerInvoke()
   at System.Threading.Tasks.Task.InnerInvokeWithArg(Task childTask)
   at System.Threading.Tasks.Task.<>c__DisplayClass11.<ExecuteSelfReplicating>b_
_10(Object param0)<---

Stopped due to error

[thinkbeforecoding]

I've already noticed this with C# assemblies from Akka.NET. The problem is that the '<' '>' chars are not escaped, and they're not valid in a file path..

[eiriktsarpalis]

Yes, I should have mentioned that it was a C# assembly in my case too.

I've subsequently noticed that this issue probably stems from the fact that accessibility modifiers are ignored in C# assemblies; internal and public types are churned out indiscriminately.

[tpetricek]

Well, the path encoding should be easy to fix :-)

The ignoring of private and internal C# members relies on F# Compiler Service, so I think we need some pointers from @dsyme on where to change things there...

[matthid]

I kind of tried to introduce C# support, however there is a bit more than just fixing this exception.
After fixing this bug (matthid/FSharp.Formatting@58e94ba) it kind of works, but methods are missing in the generated documentation (and all members of generic classes will also have no documentation).

The problem seems to be that the FSharp.Compiler.Service call doesn't return them:
matthid/FSharp.Compiler.Service@c5dfd4d

After this fix it's just a matter of generating the right XmlSignature string: (matthid/FSharp.Formatting@1bf4f92).

Maybe someone wants to review those changes and open a pull request? I'm not sure what to do because of the changes in FSharp.Compiler.Service (not sure if those changes are "correct" or if this is even a bug?).

After those changes the documentation is generated for my project flawlessly (its a bit unfortunate that I have to bundle the FSharp.Compiler.Service.dll now).

NOTE: The first commit is kind of broken in a way that the check "&& (typ.IsClass || typ.IsInterface)" must be added to line 668 (or you will get errors for some FSharp projects)