From 237e17f7175af63891e0382621c22456cb64c2c6 Mon Sep 17 00:00:00 2001 From: Andrei Fangli Date: Wed, 29 Nov 2023 12:29:03 +0200 Subject: [PATCH] Update index.html --- docs/1.0.0/index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/1.0.0/index.html b/docs/1.0.0/index.html index e46b1d52..d1e835d2 100644 --- a/docs/1.0.0/index.html +++ b/docs/1.0.0/index.html @@ -1,7 +1,7 @@ --- title: Home layout: bootstrap_5.2.3 -version: 1.0.0+5283488d7cd31f06e21c5793f9f844b32b817519 +version: 1.0.0 --- {% raw %}

CodeMap@1.0.0+5283488d7cd31f06e21c5793f9f844b32b817519

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

NamespaceDescription
CodeMap.DeclarationNodesContains the declaration node definitions corresponding to declarations of assembly members (classes, properties, methods and so on). This is the entry point for generating documentation.
CodeMap.DocumentationElementsContains the documentation element definitions corresponding to XML elements that are extracted from a documentation XML file associated to an assembly.
CodeMap.HtmlContains types for generating HTML pages.
CodeMap.ReferenceDataContains member reference definitions that can be used to create hyperlinks to referred members defined both in the documented library and dependent assemblies.

Remarks

Visual Studio enables developers to write comprehensive documentation inside their code using XML in three slashed comments, see XML Documentation Comments (C# Programming Guide) 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 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 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
  • typeparam (available only for types and methods) in .NET Core making this element obsolete in this case.
  • param (available only for delegates, constructors, methods, properties with parameters)
  • returns (available only for delegates and methods with result)
  • exception (available only for delegates, constructors, methods and properties)
  • remarks
  • example
  • value (available only for properties)
  • seealso

All of the above sections can contain documentation made out of blocks, text and limited markup. seealso does not contain any content and are interpreted as references.

The content blocks are made using the following tags:

It is not mandatory to specify the 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 or a 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 section contains three paragraphs, a code block and a list.

<remarks>
 This is my first paragraph.
@@ -193,4 +193,4 @@ 
Tables
This is where things will get a bit interesting. Tables are us
  // After all this setup, it is time to generate the HTML page.
  codeMapAssemblyDeclaration.Accept(htmlWriterDeclarationNodeVisitor);
-

Remarks

The entire documentation for all DeclarationNodes is written to a single output. Basic hash navigation is added through a simple JavaScript block allowing for only one element to be displayed at a given time. This enables sharing of links and bookmarking a specific DeclarationNode.

For each DeclarationNode a section element is generated where the ID is set to the full name reference (DeclarationNodeExtensions.GetFullNameReference(DeclarationNode). This ID can be used to reference each declaration and it is used for navigation.

Most likely there are references between assemblies for which hyperlinks need to be generated. At the very least there are the type references to .NET Framework. For this an IMemberReferenceResolver needs to be provided, there are implementation already available to get started with this quickly.

Other references

{% endraw %} \ No newline at end of file +

Remarks

The entire documentation for all DeclarationNodes is written to a single output. Basic hash navigation is added through a simple JavaScript block allowing for only one element to be displayed at a given time. This enables sharing of links and bookmarking a specific DeclarationNode.

For each DeclarationNode a section element is generated where the ID is set to the full name reference (DeclarationNodeExtensions.GetFullNameReference(DeclarationNode). This ID can be used to reference each declaration and it is used for navigation.

Most likely there are references between assemblies for which hyperlinks need to be generated. At the very least there are the type references to .NET Framework. For this an IMemberReferenceResolver needs to be provided, there are implementation already available to get started with this quickly.

Other references

{% endraw %}