Documentation is an important part of any project. When creating software, code alone is insufficient. There must be some text along with it to describe various aspects of its intended operation. It is important for the code documents to be thorough, but not so verbose that it becomes difficult to maintain them. Enter NaturalDocs. Natural Docs is an open-source documentation generator for multiple programming languages. You document your code in a natural syntax and then Natural Docs scans your code and builds HTML pages from it.

Installing NaturalDocs is pretty straightforward, first thing we have to do is get Perl 5.05 or higher installed. The NaturalDocs website has a listing of Perl versions for different platforms, I am using Active State’s ActivePerl 5.10. After downloading and running the ActivePerl install wizard, make sure to have the wizard set your system’s Perl environment variable before finishing. You can also do this yourself if you miss this step.

Next we need to download and unzip NaturalDocs itself. Once it is unzipped NaturalDocs is installed. Before testing we’re going to need to add some properly formatted documentation to one of our projects. After following the formatting guidelines on the NaturalDocs site, we’re ready to test our installation.

To test it you’re going to need to use the command line so get that opened up and navigate to the NaturalDocs directory (cd dirpath where dirpath is similar to c:\source\dirpath). Before running NaturalDocs you’re going to need to know three things in this order: 1) the path to the directory containing the files requiring documenting; 2) what type of output you want and the path to the directory that will contain it; and 3) where you are going to store the data files that NaturalDocs creates when run. Your command should look similar to:

NaturalDocs -i C:\Design Patterns\Adapter 
-o FramedHTML C:\Design Patterns\Adapter\Documentation 
-p C:\Design Patterns\Adapter\Documentation\Data

That whole command should be executed at once, with the paths provided above being replaced with the paths to your files/directories. Navigate to your output directory and you should see something like this:

Open up index.html and you should see your documentation. With all the options available for formatting and the way it delivers the documentation, NaturalDocs can be a really powerful tool to have when working on projects. There really is no excuse not to have great source documentation for each project. By using a .bat file and organizing the paths correctly, you can create a drag-and-drop file that can be added to any project. Let’s do that now.

Step one is setting up our directory structure. Create a folder and name it ‘Documentation’. Inside that folder place a copy of NaturalDocs. At the same level as your NaturalDocs folder create another folder called ‘Docs’. Open the NaturalDocs folder and create a folder called ‘Data’. You should now have a folder with the following setup:

Next we create our .bat file. Open up Notepad (or any text editor) and enter the following:

cd NaturalDocs-1.4

NaturalDocs -i ..\..\ -o FramedHTML ..\..\Documentation\Docs 
-p ..\..\Documentation\NaturalDocs-1.4\Data -s Roman 
-xi ..\..\Documentation

Save this in the root of your Documentation folder as ‘docufy.bat’. If your NaturalDocs folder has a different name than the one above go ahead and substitute it. You can also change the output style by changing the word ‘Roman’ to ‘Default’, ‘Small’, or your own style. Now you can copy the entire folder and add it to any project and by running the .bat file, have instant code documentation that can be viewed on your computer or moved to the web.

Get NaturalDocs here.

Get ActivePerl here.

Download a copy of the Documentation folder minus NaturalDocs itself. Just copy the NaturalDocs files into the NaturalDocs-1.4 directory and you should be good to go.