Add XML doc support for categorization and exclusions

FSharp.Formatting.sln

@@ -8,8 +8,6 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "project", "project", "{194B
 		.dockerignore = .dockerignore
 		.editorconfig = .editorconfig
 		.gitignore = .gitignore
-		.travis.yml = .travis.yml
-		appveyor.yml = appveyor.yml
 		build.cmd = build.cmd
 		build.fsx = build.fsx
 		build.sh = build.sh

RELEASE_NOTES.md

@@ -1,3 +1,25 @@
+## 7.2.3
+
+- support `<namespacesummary>...<namespacesummary>`
+
+- support `<namespaceremarks>...<namespaceremarks>`
+
+- support `<note>...<note>`
+
+- support `<exclude />`
+
+- allow  `<a href="..." >` in XML doc comments
+
+- document XML doc things supported
+
+## 7.2.2
+
+- instruct about settings
+
+## 7.2.1
+
+- fix images in nuget
+
 ## 7.2.0
 
 - include templates

docs/apidocs.fsx

@@ -37,21 +37,62 @@ The HTML is built by instantiating a template. The template used is the first of
 
 Usually the same template can be used as for [other content](content.html).
 
-## Classic XML Comments
+## Classic XML Doc Comments
 
-XML Comments may use [the normal F# and C# XML doc standards](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/).
+XML Doc Comments may use [the normal F# and C# XML doc standards](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/).
 
-An example of an XML documentation comment:
+In addition, you may also use
+
+* `<a href = "...">` links
+
+* Arbitrary paragraph-level HTML such as `<b>` for bold in XML doc text
+
+* `<namespacesummary>` for giving summary sections for the enclosing namespace
+
+* `<namespaceremarks>` for giving extended remarks for the enclosing namespace
+
+* `<exclude>` and `<omit>` to exclude from XML docs
+
+* `<category>` to give a category for presentation
+
+An example of an XML documentation comment, assuming the code is in namespace `TheNamespace`:
 *)
 /// <summary>
-/// Some actual comment
-/// <para>Another paragraph</para>
+///   Some actual comment
+///   <para>Another paragraph, see  <see cref="T:TheNamespace.SomeType"/>. </para>
 /// </summary>
-module Foo2 = 
-   let a = 42
+///
+/// <param name="x">The input</param>
+///
+/// <returns>The output</returns>
+///
+/// <example>
+///   Try using
+///   <code>
+///      open TheNamespace
+///      SomeModule.a
+///   </code>
+/// </example>
+///
+/// <namespacesummary>A namespace to remember</namespacesummary>
+///
+/// <namespaceremarks>More on that</namespaceremarks>
+///
+/// <category>Foo</category>
+///
+
+module SomeModule = 
+   let someFunction x = 42 + x
 
-(**
+/// <summary>
+///   A type, see  <see cref="T:TheNamespace.SomeModule"/> and
+///  <see cref="T:TheNamespace.SomeModule.someFunction"/>. </para>
+/// </summary>
+///
+type SomeType() =
+   member x.P = 1
 
+(**
 
 ## Go to Source links
 

docs/codeformat.fsx

@@ -49,7 +49,7 @@ example shows, you can specify which version of `FSharp.Compiler.dll` to use.
 Processing F# source
 --------------------
 
-The formatting agent provides a `ParseSource` method (together with an asynchronous
+The formatting agent provides a `ParseAndCheckSource` method (together with an asynchronous
 version for use from F# and also a version that returns a .NET `Task` for C#).
 To call the method, we define a simple F# code as a string:
 *)
@@ -58,7 +58,7 @@ let source = """
     let hello () = 
       printfn "Hello world"
   """
-let snippets, errors = formattingAgent.ParseSource("C:\\snippet.fsx", source)
+let snippets, errors = formattingAgent.ParseAndCheckSource("C:\\snippet.fsx", source)
 
 (**
 When calling the method, you need to specify a file name and the actual content

docs/content.fsx

@@ -79,7 +79,7 @@ See [Styling](styling.html) for information about template parameters and stylin
 | `fsdocs-list-of-namespaces`   | HTML `<li>` list of namespaces with links                     |  
 | `fsdocs-list-of-documents`    | HTML `<li>` list of documents with  titles and links          |  
 | `fsdocs-page-title`           | First h1 heading in literate file. Generated for API docs     | 
-| `fsdocs-source`               | Original script source                                        | 
+| `fsdocs-source`               | Original literate script or markdown source                   | 
 | `fsdocs-tooltips`             | Generated hidden div elements for tooltips                    | 
 
 

docs/content/fsdocs-default.css

@@ -62,6 +62,10 @@ body {
     margin: 0px 0px 20px 0px;
 }
 
+#fsdocs-content li {
+    margin: 0px 0px 15px 0px;
+}
+
 /*--------------------------------------------------------------------------
   Formatting tables in fsdocs-content, using docs.microsoft.com tables
 /*--------------------------------------------------------------------------*/
@@ -99,8 +103,8 @@ body {
     }
 
     /* suppress the top line on inner lists such as tables of exceptions */
-    #fsdocs-content .table .inner-list td,
-    #fsdocs-content .table .inner-list th {
+    #fsdocs-content .table .fsdocs-exception-list td,
+    #fsdocs-content .table .fsdocs-exception-list th {
         border-top: 0
     }
 

docs/styling.md

@@ -45,7 +45,16 @@ the standard template.  The CSS classes of generated content are:
 | `.fsdocs-member-tooltip `      |  generated tooltips for members |
 | `.fsdocs-xmldoc `      |  generated xmldoc sections  |
 | `.fsdocs-entity-list `      |  generated entity lists |
-| `.fsdocs-member-list `      |  generated member lists |
+| `.fsdocs-exception-list `      |  generated exception lists |
+| `.fsdocs-summary`      |  the 'summary' section of an XML doc |
+| `.fsdocs-remarks`      |  the 'remarks' section of an XML doc |
+| `.fsdocs-params`      |  the 'parameters' section of an XML doc |
+| `.fsdocs-param`      |  a 'parameter' section of an XML doc |
+| `.fsdocs-param-name`      |  a 'parameter' name of an XML doc |
+| `.fsdocs-returns`      |  the 'returns' section of an XML doc |
+| `.fsdocs-example`      |  the 'example' section of an XML doc |
+| `.fsdocs-note`      |  the 'notes' section of an XML doc |
+| `.fsdocs-para`      |  a paragraph of an XML doc |
 
 Some generated elements are given specific HTML ids:
 

src/Common/AssemblyInfo.cs

@@ -4,17 +4,17 @@
 
 [assembly: AssemblyProduct("FSharp.Formatting")]
 [assembly: AssemblyDescription("A package of libraries for building great F# documentation, samples and blogs")]
-[assembly: AssemblyVersion("7.1.8")]
-[assembly: AssemblyFileVersion("7.1.8")]
-[assembly: AssemblyInformationalVersion("7.1.8")]
+[assembly: AssemblyVersion("7.2.2")]
+[assembly: AssemblyFileVersion("7.2.2")]
+[assembly: AssemblyInformationalVersion("7.2.2")]
 [assembly: AssemblyCopyright("Apache 2.0 License")]
 namespace System {
     internal static class AssemblyVersionInformation {
         internal const System.String AssemblyProduct = "FSharp.Formatting";
         internal const System.String AssemblyDescription = "A package of libraries for building great F# documentation, samples and blogs";
-        internal const System.String AssemblyVersion = "7.1.8";
-        internal const System.String AssemblyFileVersion = "7.1.8";
-        internal const System.String AssemblyInformationalVersion = "7.1.8";
+        internal const System.String AssemblyVersion = "7.2.2";
+        internal const System.String AssemblyFileVersion = "7.2.2";
+        internal const System.String AssemblyInformationalVersion = "7.2.2";
         internal const System.String AssemblyCopyright = "Apache 2.0 License";
     }
 }

src/Common/AssemblyInfo.fs

@@ -4,16 +4,16 @@ open System.Reflection
 
 [<assembly: AssemblyProductAttribute("FSharp.Formatting")>]
 [<assembly: AssemblyDescriptionAttribute("A package of libraries for building great F# documentation, samples and blogs")>]
-[<assembly: AssemblyVersionAttribute("7.1.8")>]
-[<assembly: AssemblyFileVersionAttribute("7.1.8")>]
-[<assembly: AssemblyInformationalVersionAttribute("7.1.8")>]
+[<assembly: AssemblyVersionAttribute("7.2.2")>]
+[<assembly: AssemblyFileVersionAttribute("7.2.2")>]
+[<assembly: AssemblyInformationalVersionAttribute("7.2.2")>]
 [<assembly: AssemblyCopyrightAttribute("Apache 2.0 License")>]
 do ()
 
 module internal AssemblyVersionInformation =
     let [<Literal>] AssemblyProduct = "FSharp.Formatting"
     let [<Literal>] AssemblyDescription = "A package of libraries for building great F# documentation, samples and blogs"
-    let [<Literal>] AssemblyVersion = "7.1.8"
-    let [<Literal>] AssemblyFileVersion = "7.1.8"
-    let [<Literal>] AssemblyInformationalVersion = "7.1.8"
+    let [<Literal>] AssemblyVersion = "7.2.2"
+    let [<Literal>] AssemblyFileVersion = "7.2.2"
+    let [<Literal>] AssemblyInformationalVersion = "7.2.2"
     let [<Literal>] AssemblyCopyright = "Apache 2.0 License"