net8.0 and list support (#34) +semver: major

Author: charlesdevandiere

.gitignore

@@ -327,3 +327,7 @@ ASALocalRun/
 
 # MFractors (Xamarin productivity tool) working folder 
 .mfractor/
+
+
+# output
+out/

.vscode/extensions.json

@@ -1,9 +1,7 @@
 {
   "recommendations": [
-    "ms-dotnettools.csharp",
     "editorconfig.editorconfig",
-    "k--kato.docomment",
-    "formulahendry.dotnet-test-explorer",
+    "ms-dotnettools.csdevkit",
     "redhat.vscode-yaml"
   ]
 }

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Charles de Vandière
+Copyright (c) 2024 Charles de Vandière
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

docs/sample/myclasslib.myclass.md

@@ -87,6 +87,9 @@ if (true)
 }
 ```
 
+- **item 1** - The first item. `1`
+- **item 2** - The second item. `2`
+
 ### **MyClass(String, Int32)**
 
 Initializes a new instance of the [MyClass](./myclasslib.myclass) class.

docs/sample/myclasslib.myenum.md

@@ -13,7 +13,7 @@ public enum MyEnum
 ```
 
 Inheritance [Object](https://docs.microsoft.com/en-us/dotnet/api/system.object) → [ValueType](https://docs.microsoft.com/en-us/dotnet/api/system.valuetype) → [Enum](https://docs.microsoft.com/en-us/dotnet/api/system.enum) → [MyEnum](./myclasslib.myenum)<br>
-Implements [IComparable](https://docs.microsoft.com/en-us/dotnet/api/system.icomparable), [IFormattable](https://docs.microsoft.com/en-us/dotnet/api/system.iformattable), [IConvertible](https://docs.microsoft.com/en-us/dotnet/api/system.iconvertible)
+Implements [IComparable](https://docs.microsoft.com/en-us/dotnet/api/system.icomparable), [ISpanFormattable](https://docs.microsoft.com/en-us/dotnet/api/system.ispanformattable), [IFormattable](https://docs.microsoft.com/en-us/dotnet/api/system.iformattable), [IConvertible](https://docs.microsoft.com/en-us/dotnet/api/system.iconvertible)
 
 ## Fields
 

generate-sample-doc.bat

@@ -1,3 +1,5 @@
 @echo off
-dotnet build
-.\src\XMLDoc2Markdown\bin\Debug\net6.0\XMLDoc2Markdown.exe .\sample\MyClassLib\bin\Debug\netstandard2.0\MyClassLib.dll .\docs\sample --examples-path .\sample\docs\examples --github-pages --back-button
+
+dotnet build -o ./out
+
+./out/XMLDoc2Markdown.exe ./out/MyClassLib.dll ./docs/sample --examples-path ./sample/docs/examples --github-pages --back-button

generate-sample-doc.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+rm -rf ./out
+
+dotnet build -o ./out
+
+./out/XMLDoc2Markdown ./out/MyClassLib.dll ./docs/sample --examples-path ./sample/docs/examples --github-pages --back-button

sample/MyClassLib/MyClass.cs

@@ -71,6 +71,16 @@ public class MyClass : IMyInterface
         ///     Console.WriteLine(foo.ToString());
         /// }
         /// </code>
+        /// <list type="bullet">
+        ///     <item>
+        ///         <term>item 1</term>
+        ///         <description>The first item. <c>1</c></description>
+        ///     </item>
+        ///     <item>
+        ///         <term>item 2</term>
+        ///         <description>The second item. <c>2</c></description>
+        ///     </item>
+        /// </list>
         /// </remarks>
         public MyClass()
         { }
@@ -110,15 +120,6 @@ public void Do(string firstParam, int secondParam)
         public int DoGeneric<T>(T value)
         { throw new ArgumentException(); }
 
-        /// <summary>
-        /// Do some thing.
-        /// </summary>
-        /// <typeparam name="T">The type argument. Used by <see cref="DoGeneric{T}(T)"/>.</typeparam>
-        /// <param name="value">The param. Used by <see cref="DoGeneric{T}(T)"/>.</param>
-        /// <returns>Returns a value <see cref="int"/>.</returns>
-        /// <exception cref="ArgumentException">Thrown instead of <see cref="Exception"/>.</exception>
-        public int DoGeneric<T>(T value) { throw new ArgumentException(); }
-
         /// <summary>
         /// Gets some thing.
         /// </summary>

src/XMLDoc2Markdown/TypeDocumentation.cs

@@ -194,7 +194,7 @@ private void WriteMemberInfoRemarks(XElement memberDocElement)
         }
     }
 
-    private MarkdownTextElement XElementToMarkdown(XElement element)
+    private object XElementToMarkdown(XElement element)
     {
         return element.Name.ToString() switch
         {
@@ -205,6 +205,7 @@ private MarkdownTextElement XElementToMarkdown(XElement element)
             "para" => this.XNodesToMarkdownParagraph(element.Nodes()),
             "example" => this.XNodesToMarkdownParagraph(element.Nodes()),
             "code" => new MarkdownCode("csharp", TypeDocumentation.FormatCodeElementValue(element.Value)),
+            "list" => this.XElementToMarkdownList(element),
             _ => new MarkdownText(element.Value)
         };
     }
@@ -268,7 +269,7 @@ private MarkdownParagraph XNodesToMarkdownParagraph(IEnumerable<XNode> nodes)
 
         foreach (XNode node in nodes)
         {
-            MarkdownTextElement element = this.XNodeToMarkdown(node);
+            object element = this.XNodeToMarkdown(node);
             if (element is null)
             {
                 continue;
@@ -305,7 +306,76 @@ private MarkdownParagraph XNodesToMarkdownParagraph(IEnumerable<XNode> nodes)
         return new MarkdownParagraph(string.Join(Environment.NewLine, blocks));
     }
 
-    private MarkdownTextElement XNodeToMarkdown(XNode node)
+    private MarkdownList XElementToMarkdownList(XElement element)
+    {
+        MarkdownList markdownList = element.Attribute("type")?.Value switch
+        {
+            "number" => new MarkdownOrderedList(),
+            _ => new MarkdownList()
+        };
+
+        foreach (XElement item in element.Elements("item"))
+        {
+            MarkdownText markdownListItem = new(string.Empty);
+
+            IEnumerable<XNode> term = item.Element("term").Nodes();
+
+            MarkdownText markdownTerm = null;
+
+            foreach (XNode node in term)
+            {
+                object md = this.XNodeToMarkdown(node);
+                if (md is MarkdownInlineElement inlineElement)
+                {
+                    if (markdownTerm is null)
+                    {
+                        markdownTerm = new MarkdownText(inlineElement);
+                    }
+                    else
+                    {
+                        markdownTerm.Append(inlineElement);
+                    }
+                }
+            }
+
+            if (markdownTerm is not null)
+            {
+                markdownListItem.Append(new MarkdownStrongEmphasis(markdownTerm));
+            }
+
+            IEnumerable<XNode> description = item.Element("description").Nodes();
+
+            MarkdownText markdownDescription = null;
+
+            foreach (XNode node in description)
+            {
+                object md = this.XNodeToMarkdown(node);
+                if (md is MarkdownInlineElement inlineElement)
+                {
+                    if (markdownDescription is null)
+                    {
+                        markdownDescription = new MarkdownText(inlineElement);
+                    }
+                    else
+                    {
+                        markdownDescription.Append(inlineElement);
+                    }
+                }
+            }
+
+            if (markdownDescription is not null)
+            {
+                markdownListItem.Append(" - ");
+                markdownListItem.Append(markdownDescription);
+            }
+
+            markdownList.AddItem(markdownListItem);
+        }
+
+        return markdownList;
+    }
+
+    private object XNodeToMarkdown(XNode node)
     {
         return node switch
         {

src/XMLDoc2Markdown/XMLDoc2Markdown.csproj

@@ -2,15 +2,15 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net6.0</TargetFramework>
+    <TargetFramework>net8.0</TargetFramework>
     <LangVersion>latest</LangVersion>
     <Version>0.0.0</Version>
     <ToolCommandName>xmldoc2md</ToolCommandName>
     <PackAsTool>true</PackAsTool>
     <IsPackable>true</IsPackable>
 
     <Authors>Charles de Vandière</Authors>
-    <Copyright>© 2022 Charles de Vandière</Copyright>
+    <Copyright>© 2024 Charles de Vandière</Copyright>
     <Product>XMLDoc2Markdown</Product>
     <Title>XMLDoc2Markdown</Title>
     <Description>Tool to generate markdown from C# XML documentation.</Description>
@@ -40,7 +40,7 @@
   <ItemGroup>
     <PackageReference Include="MarkdownBuilder" Version="0.2.0" />
     <PackageReference Include="Microsoft.Extensions.CommandLineUtils" Version="1.1.1" />
-    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.1.1" PrivateAssets="All"/>
+    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All"/>
   </ItemGroup>
 
 </Project>