Readable Source Code Documentation
for 21 Programming Languages
Natural Docs lets you document code written in any of 21 programming languages, plus it can be easily extended for more so whatever you use, it can too. And if your project uses multiple languages, no problem! It will all be included in the same set of documentation.
Natural Docs also speaks your other language... English! Its comments are designed to be very natural and readable so they're just as usable in the source code as they are in the generated documentation. No weird syntax or tags scattered everywhere.
Natural Docs' generated documentation is pretty and powerful, with three independently scrolling panels, dynamic menus, search, and pop-up summaries when you hover over links. All its features work wherever you put it, be it a web server, a network share, or just opened from your hard drive.
Wrapping up 2.2.
That's it, plus some internal cleanup work. Since everything seems pretty stable I'm deeming this a release candidate. If nothing pops up in the next few weeks this will be 2.2.
I really need to start wrapping up 2.2. So what's new in development release 4?
Simpler Options for Custom Home Pages
You can now add "Home Page: [file name]" to Project.txt as well. One option is to point it to a documented source file which lets you create a home page in Natural Docs' syntax. Just create a .txt file in your source tree, add Natural Docs content, and point Project.txt to it.
Another option is to point it to a .html file and that will be used as the home page instead. It doesn't have to appear in the source tree so you can put it in your project configuration folder if you want. However, it's a standalone file so you'd have to embed any CSS it needs directly in it.
Like before, you can put these strings anywhere in the HTML file and Natural Docs will replace them with the project information. This is useful if you wanted to add a build timestamp that updates automatically.
As a reminder, custom home pages replace this part of the site:
The title, search box, and side menu will still be visible. If you use a source file as the home page the left side menu will still show the starting menu instead of jumping to that page. This feature isn't documented on the web site yet but will be once 2.2 is released.
Natural Docs expects Unicode source files by default. It will automatically detect and handle all forms of UTF-8, UTF-16, and UTF-32. But what if you have something different?
Now you can manually specify character encodings for your source files. You do this by adding Encoding lines to Project.txt:
This sets the default encoding for all files to Windows 1252 (Western European). If it appears in the project information section it will be the default for all source folders. If you put it under a Source Folder heading it will be the default for just that folder.
Encoding: Macintosh *.mac
This sets the encoding for all .mac files to Macintosh (Roman/Western European). Like before, if it appears in the project information it will apply to all source folders, but if it appears under a Source Folder heading it will only apply in that folder.
Encoding: iso-8859-1 C:\My Project\Source\Module1
This sets the encoding for all files in the Module1 folder to ISO 8859-1. This rule takes precedence over any rules for parent folders, so all .mac files appearing in Module1 are also ISO 8859-1. You can only put Encoding lines that specify folders like this under Source Folder headings.
Encoding: shift_jis C:\My Project\Source\Module1\*.txt
This sets the encoding for all .txt files in the Module1 folder to Shift JIS. If you needed to reapply the .mac rule for this folder you could also include "Encoding: Macintosh C:\My Project\Source\Module1\*.mac". Since these rules specify folders they can only appear under Source Folder headings.
All operating systems may not support the same encodings. You can see which ones are available on yours by running Natural Docs with the --list-encodings command line option. You can use either the name or the code page number (the second and third columns) in Project.txt but not the description (the first column.)
Natural Docs now supports <a href=""> and <see href=""> links in XML comments. It will also detect bare URLs and e-mail addresses and convert them to links as well.
Tweaks and Fixes
This won't mean much to you right now but it lays the groundwork for the future. How hierarchies are handled internally has been refactored, which means it will be much easier to add new ones going forward. Instead of hard-coded logic for classes and databases there's a more generic system that can handle those plus other future ones. They aren't configurable through text files like the rest of Natural Docs, and that may or may not change in the future, but it's the last piece that needed to be put in place to start on full SystemVerilog support.