XML Code Documentation
Microsoft Visual Studio allows developers to write source code documentation, which can be compiled via third-party tools into API help files. 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 was abandoned in 2007, but thankfully Microsoft now provides a tool called 'Sandcastle', which we suggest you to use:
- 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
Whether you write your own code, extend or hijack the Ecopath sources for illegitimate purposes, you may want to add code documentation of your own. Lots of information is available on XML tags supported in Visual Studio. A few comprehensive links are:
- Windows Assistance Markup Language (MAML) - XML standard that defines the source code comments structure.
- 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.
