As you know, the text after "///" gets whacked straight into an XMLDoc file under a <summary> tag. That's pretty much the full story. It tends to get used as an anonymous blob in HTML generation and in interactive help in Visual Studio.

Because of this dual use only restricted formatting really makes sense. We do tend to use very simple HTML markup (<b>, <i>, <a>, etc.) in the F# documentation. We figure these can also be read even by human readers who happen to be reading some other formatting of the XML help, e.g. in popup help in Visual Studio. However ideally we would follow a fully standard set of XMLDoc authoring guidelines and take account of this in HTML generation. But for the moment minimalistic embedded HTML is the recommended use of this facility. Of course you can always link to more sophisticated content. (** *) are single-line only and are is used for cross-compiling OCaml code (you can also do multi-line by using ///, but you have to surround the comments by (*F#... F#*), which is annoying). We use a small F# program that loads the generated XML file as an XMLDocument, thereby sanity checking it. Here's the program: <code lang=fsharp> open System.Xml let doc = new XmlDocument() let file = Sys.argv.(1);; printf "Testing %s" file;; doc.Load(file);; </code> HTML generation is enabled on the command-line compiler and in the VS project options by the flags: --generate-html: Generate HTML documentation. --html-output-directory <string>: Output directory for HTML documentation. --html-css <string>: Set the name of the Cascading Style Sheet for HTML docs. --html-namespace-file <string>: Set the name of the master namespaces.html file assumed to be in the output directory. --html-namespace-file-append: Append to the master namespace file when generating HTML documentation. The main thing with HTML generation is that you should take a copy of the msdn.css stylesheet in order to get good looking docs. If you have feature requests for HTML generation please let us know. Don