What is the best way of documenting f# code?

Question

I have tried Sandcastle with the patches included with the guided GUI installation, but unless I am doing something very wrong it's basically unsuitable for documenting F# code (even if it would work really well for C#). Maybe it works for others, in which case I would be very grateful for a short complete example that I could start from. Many thanks.

I am aware of Sandcastle doesn't output everything from a F# assembly , but the project referenced there does not yet appear ready for prime time.

There must surely be something that works reliably and is "good enough"? Many thanks for any suggestions.

Edit: Many thanks to everyone who replied. Brian's answer was closest to what I wanted, so I will accept it. However, the outcome is that there does not appear to be a solution that is both suited to F# and that works reliably. I will stick with textual comments for now.

I expect FsHtmlDoc.exe will start to work at some point. While I cannot rule out that it works already and I just did not use it correctly, googling it suggests I am not the only one to find it is not yet perfect.

Answer 1

I know next to nothing about Sandcastle, but note that like C#, in F# you can use triple-slash comments, and they will be output in the XML documentation file that the compiler outputs (in VS, on the project properties page, build tab, check the 'Xml documentation file' checkbox; on the command line, use the --doc argument to fsc.exe.)

Also, see FsHtmlDoc.exe in the PowerPack.

Answer 2

You could also look at Focco

It produces a nice html based documentation. See here for an example:

Answer 3

You could also check out ApiStack from IntelliFactory. I realize Focco requires a very different approach if you already have a lot of standard XML doc comments.

Answer 4

I haven't used it, but it might be worth giving docu a try...