Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/andrei15193/codemap

An extensible tool for generating documentation for your .NET libraries. Generate HTML, Markdown or in any other format, customise the documentation at your discretion.
https://github.com/andrei15193/codemap

documentation documentation-code documentation-generator documentation-tool generator html site-generator

Last synced: 5 months ago
JSON representation

An extensible tool for generating documentation for your .NET libraries. Generate HTML, Markdown or in any other format, customise the documentation at your discretion.

Awesome Lists containing this project

README 

          
![Build and Deploy](https://github.com/Andrei15193/CodeMap/workflows/Build%20and%20Deploy/badge.svg)



Visual Studio enables developers to write comprehensive documentation inside

their code using XML in three slashed comments,

see [XML Documentation Comments (C# Programming Guide)](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments) for

more details about supported tags.



When we build a project that has been configured to generate XML documentation

files (simply specify the output path where resulting files should be saved)

Visual Studio will look for this file and display the respective documentation

in IntelliSense.



This is great and all library owners should be writing documentation like this

in their code, however there aren't that many tools out there that allow us to

transform the XML generated documentation into something else, say JSON or

custom HTML, to display the exact same documentation on the project's website.



Having a single source for documentation is the best way to ensure consistency,

what you see in code is what you see on the project's website. There are no

discrepancies. Writing all documentation in code may upset developers, but

after all they know best what the code they are writing is all about.



CodeMap aims to bring a tool into the developers hands that allows them to

generate any output format they wish from a given assembly and associated

XML documentation.



This is done following the visitor design pattern, an assembly is being visited

and all elements that make up an assembly get their turn. When you want to

generate a specific output (say Markdown or Creole) you simply implement your

own visitor.



There are some elements that do not have XML documentation correspondents, such

as assemblies, modules and namespaces. You cannot write documentation for

neither in code and have it generated in the resulting XML document.



This tool does not work directly on the XML file but rather on a representation

of the file (XDocument), this allows for the document to be loaded, updated if

necessary and only then processed. This enables the tool to support additions

to the standard XML document format allowing for extra documentation to be

manually added. If you want to add specific documentation to a namespace, you

can, but you have to do it manually which means you follow the XML document

structure as well.



This project exposes an XML Schema (.xsd) that is used for validating an XML

document containing documentation to ensure that it is being correctly

processed.



Exceptions

----------



Some elements are ignored when processing the XML document because they either

are complex to use or there is little support for them.



* [include](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/include)

is being ignored because its usage is rather complex and can be misleading.

The documentation is being kept separate from the source code which can easily

lead to discrepancies when changes to code occur.



* [permission](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/permission)

is being ignored because its usage is more of an edge case and code permissions

are not supported in .NET Core making this element obsolete in this case.



Interpretations

---------------



There are XML elements defined for various sections and limited markup support.

The main sections for documentation are the following:



* [summary](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/summary)

* [typeparam](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/typeparam) (available only for types and methods)

* [param](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/param) (available only for delegates, constructors, methods, properties with parameters)

* [returns](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/returns) (available only for delegates and methods with result)

* [exception](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/exception) (available only for delegates, constructors, methods and properties)

* [remarks](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/remarks)

* [example](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/example)

* [value](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/value) (available only for properties)

* [seealso](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/seealso)



All of the above sections can contain documentation made out of blocks, text

and limited markup. [seealso](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/seealso) does

not contain any content and are interpreted as references.



The content blocks are made using the following tags:



* [para](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/para)

* [code](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/code)

* [list](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/list)



It is not mandatory to specify the [para](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/para) element

because it is inferred. It is mandatory to do so only when you want to

distinguish two paragraphs that are one after the other, but if there is plain

text that has a [code](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/code)

or a [list](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/list) element

then the text before the respective tag is considered a paragraph and the text

afterwards is considered a separate paragraph.



For instance, the following [returns](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/returns) section

contains three paragraphs, a code block and a list.



```xml



This is my first paragraph.



This is a code block



This is my second paragraph.



    Item 1

    Item 2

    Item 3



This is my third paragraph.



```



To distinguish two paragraphs one after the other you need to use the [para](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/para) tag.



```xml



    This is my first paragraph.



    This is my second paragraph.



```



Each content block can contain plain text and limited markup using the following tags:



* [c](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/code-inline)

* [see](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/see)

* [paramref](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/paramref)

* [typeparamref](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/typeparamref)



Some XML elements lack a proper documentation and are not properly interpreted

by Visual Studio.



[List](https://learn.microsoft.com/dotnet/csharp/programming-guide/xmldoc/list) is

one of these elements, regardless of how you define the list element, Visual

Studio will display the contents as plain text. This is understandable, there

should not be such complex markup in the summary of a method or parameter

description.



One the other hand, the lack of documentation for this element and the lack of

proper interpretation allows for more flexibility when it comes to parsing

lists. This tool parses lists as follows:



### Simple Lists



This corresponds to list type `bullet` and `number` that have no `listheader`

element.



To define a list simply use the `list` element, specify a type (the default is

`bullet`) and then define each item using an `item` element. Optionally include

a `description` subelement (this is more for compliance with the documentation,

having a `description` element or not makes no difference).



#### Examples



Bullet (unordered) list:



```xml



    this is an item

    

        this is an item using description, it is the same as the first one

    

    the description element is optional, use at your discretion



```



Number (ordered) list:



```xml



    first item

    second item

    third item



```



### Definition Lists



This is where it can get a bit confusing. The definition list is inferred by

the given list type (`bullet` or `number`) or lack of this attribute.

Definition lists cannot be ordered or unordered, they define a list of terms.

This makes the type attribute rather useless in this case, it can be safely

omitted since the default is `bullet` and alligns with the interpretation.



To create a definition list it must either have a title or one of its items

to contain the `term` element. The title is optional, however if the `list`

element is empty it will not be inferred as a definition list!



Optionally, a definition list can have a title which is defined using the

`listheader` element. The title can be written directly in the element or

can be wrapped in a `term` element.



#### Examples



Simple definition list:



```xml



    

        Exception

        Describes an abnormal behaviour

    

    

        Logging

        Something we should be doing

    

    

        HTTP

        HyperText Transfer Protocol, today's standard for communication

    



```



Definition list with title:



```xml



    Music Genres

    

        Pop

        Very popular (hence the name) genre, mostly singing nonsence.

    

    

        Rock

        Experiences with depth that are very musical with some grotesque exceptions that seem more like yelling than singing.

    

    

        EDM

        Electronic Dance Music, less singing mostly used for background noise or to help get into a specific mood.

    



```



Same definition list, we can wrap the title in a `term` element to conform with

the documentation:



```xml



    

        Music Genres

    

    

        Pop

        Very popular (hence the name) genre, mostly singing nonsence.

    

    

        Rock

        Experiences with depth that are very musical with some grotesque exceptions that seem more like yelling than singing.

    

    

        EDM

        Electronic Dance Music, less singing mostly used for background noise or to help get into a specific mood.

    



```



A definition list without a term for its second item:



```xml



    

        LOL

        Usually meaning laughing out loud, can be confused with League of Legends, a very popular video game.

    

    

        For some reason I forgot to mention the term I am currently describing, Infer this!

    



```



### Tables



This is where things will get a bit interesting. Tables are useful in a lot of

scenarios, however there is no explicit syntax for them.



To define a table specify the `type` of a `list` to `table`. To define the

header rows (if any) use the `listheader` element, to define each column

header specify multiple `term` elements.



To define each row use the `item` element and for each column use a

`description` element.



The number of columns is determined by the maximum number of `term` or

`description` elements found in an enclosing element (`listheader` or `item`).

If there are missing values for a column header or row then they will be filled

with blank.



#### Examples



Simple table:



```xml



    

        Column 1

        Column 2

    

    

        Row 1, Column 1

        Row 1, Column 2

    

    

        Row 2, Column 1

        Row 2, Column 2

    

    

        Row 3, Column 1

        Row 3, Column 2

    



```



Table without heading:



```xml



    

        Row 1, Column 1

        Row 1, Column 2

    

    

        Row 2, Column 1

        Row 2, Column 2

    

    

        Row 3, Column 1

        Row 3, Column 2

    



```



Table with missing values for last column:



```xml



    

        Column 1

    

    

        Row 1, Column 1

    

    

        Row 2, Column 1

        Row 2, Column 2

    

    

        Row 3, Column 1

    



```