XML Code Documentation

Microsoft Visual Studio allows code documentation to be incorporated in supported sources, which can be compiled via third-party tools into API help files. The structure of source code comments must adhere to the ​Windows Assistance Markup Language (MAML) standard. This section explains how to generate EwE6 API help files from the EwE6 source code projects.

In the past we used ​NDoc to create API documentation of our sources. The NDoc project has been abandoned in 2007, but thankfully Microsoft supports a tool called '​Sandcastle'.

• Download and install Sandcastle ​here
• Sandcastle has no GUI front-end. For this, download and install Sandcastle Help File Builder ​here

Once Sandcastle and Sandcastle help file builder are installed, you can generate the EwE6 API help file:

• Open Sandcastle Help File Builder and load the EwE6 help file project. This project is included with the EwE6 sources at Ecopath6\Sources\Documentation\EwECore.shfbproj
• To Build documentation, Click on Documentation > Build Project
• To View documentation, Click on Documentation > View Help File > View Help File

The EwE6 API code documentation is automatically generated on a daily basis and is posted online. You can accessed this information  ​here.

Links

Lots of information is available on XML tags supported in Visual Studio. A few comprehensive links are:

• ​XML comments overview - Microsoft XML comments primer in C# syntax, with detailed info on sub-tags such as <list type="...">. A good read.
• ​XML comments guidelines - XML comments usage guidelines
• ​Another overview - Somebody else did a much better job at providing an overview than us ;-)

Handy but under-documented features

A few handy-dandy experiences that we want to share:

• SandCastle supports the <​inheritdoc cref="..."/> tag, which can save a lot of time.