CuginiTech.MarkdownComments 1.0.3

MarkdownComments

Yet another tool to transpose C# comments to markdown. Makes a single Markdown file and can handle generics.

Quick start

In your c# project folder you can install this tool locally.

dotnet new tool-manifest # if you are setting up this repo
dotnet tool install --local CuginiTech.MarkdownComments

Set your project to "Generate a file containing API documentation."

Then after building the xml file you can run the following

dotnet MarkdownComments --source path-to-doc.xml --markdown path-to-readme.md

Or you can add it to you csproj file.

<Target  Name="PostBuild" AfterTargets="PostBuildEvent">
    <Exec Command="dotnet MarkdownComments --source Doc.xml --markdown $(MSBuildProjectDirectory)\README.md" WorkingDirectory="$(MSBuildProjectDirectory)\$(OutputPath)" />
</Target>

Example

  /// <summary>
  /// StringConst is a simple class to make string constants that are isolated to the parent class.
  /// This allows strings to be made that behave more like enums.
  ///
  /// <example>
  /// <code><![CDATA[
  /// public sealed class Dogs
  /// {
  ///     public static readonly StringConst<Dogs> Candy = "Candy";
  ///     public static readonly StringConst<Dogs> Trudie = "Trudie";
  ///     public static readonly StringConst<Dogs> Fifi = "Fifi";
  /// }
  ///
  /// public sealed class People
  /// {
  ///     public static readonly StringConst<People> Hostess = "Candy";
  ///     public static readonly StringConst<People> Friend = "Trudie";
  ///     public static readonly StringConst<People> StereoType = "Fifi";
  /// }
  ///
  /// ]]></code>
  /// </example>
  /// </summary>
  /// <typeparam name="T">Class for constants to belong to.</typeparam>
  ```

Becomes 

## Class StringConst&lt;T&gt;

StringConst is a simple class to make string constants that are isolated to the parent class.
This allows strings to be made that behave more like enums.

### StringConst example

```c#
public sealed class Dogs
{
  public static readonly StringConst<Dogs> Candy = "Candy";
  public static readonly StringConst<Dogs> Trudie = "Trudie";
  public static readonly StringConst<Dogs> Fifi = "Fifi";
}

public sealed class People
{
  public static readonly StringConst<People> Hostess = "Candy";
  public static readonly StringConst<People> Friend = "Trudie";
  public static readonly StringConst<People> StereoType = "Fifi";
}

Type parameter T Class for constants to belong to. CDATA escapes allows the code to appear more readable.

Typeparam helps with setting the names of generics. And as it is tagged in the comment in a number it also sets the order of appearance.

For methods having param sets the name of method variables. One extra item is the c# xml documentation does not give details on a return method type. But it allows yo to add extra attributes.

So to set a return type of a method you can do the following

/// <returns type="bool">True if values are same.</returns>

And the type will be displayed as bool.

Parameters

Source file

--source <file>

-s <file>

A required parameter that is the c# generated xml file for documentation. An error will occur if not supplied.

Markdown file

--markdown <file>

-m <file>

A required file to denote where the markdown is to be stored. If the destination directory is not found then markdown comments will try to estblish the path.

Template file

--template <file>

-t <file>

If you want to wrap some markdown around the enitre file you can add the template parameter.

dotnet MarkdownComments --template my-doc.md --source path-to-doc.xml --markdown path-to-readme.md

In that file you can add markdown to appear at the start and the end of the generated file. To delineate the file with a single line with the escape sequence ${BODY}

# This will appear at the top
${BODY}
## The end

Ignore file

--ignore <file>

-i <file>

dotnet MarkdownComments --markdown my-doc.md --source path-to-doc.xml --ignore .mdignore

Ignore allows classes and methods to not appear in the documentation. This can be useful if the documentation is either not ready or the feature is not ready for release.

Example format below

# Markdown syntax, lines starting with a hash are treated as comments
#
# ignore entire class.
namespace.classname

# ignore method
namespace.classname.method

# match by wildcard
namesp*.classn*

# or more typical
namespace.*

Verbose

Verbose is just a flag that will show more information when generating markdown. It is useful to use to see the full names of the classes and methods that can be ingored.

dotnet MarkdownComments --markdown my-doc.md --source path-to-doc.xml --verbose