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.