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.
Well that was quick. Guess I forgot an if statement which messes things up when an image appears in a global comment instead of in a class. But that's what betas are for, so have another one with the fix.
Time to wrap up the pre-releases. I consider 2.1 done, I'm just going to release it as a beta for a month to see if anyone finds any bugs before rechristening it 2.1 proper. So what's new?
I finally finished image support, which was the biggest thing missing from 2.0 that was in 1.5. To refresh your memory on how it works, you just add (see filename.jpg) to a comment. There's two ways to do it:
// If you put it in the middle of a paragraph like this (see logo.png) it will
// If you give it its own paragraph like this, it will simply be replaced by
You can use PNG, GIF, JPG, SVG, and BMP files. You can include part of a path, such as (see images/diagram.svg). By default this is relative to the source file the comment appears in, but you can also specify image folders in Project.txt and on the command line with -img. It will search all these locations when looking for the image.
Behind the Scenes
I finished the change management refactoring I started earlier, this time doing the HTML generation code. It took a lot longer than anticipated but now it's much cleaner with better separation of duties, which in turn made adding image support much more manageable. I'm hoping it will continue to pay off like that going forward. I don't think people realize how involved it can be to keep Natural Docs' build process differential. If it was rebuilding the entire documentation set on every run it would be easy, but if you only want to update the things that changed you have to be able to track every dependency and cascading effect every potential change has. It makes it harder to write but so much faster to run, which allows you to continuously update your documentation as you work.
I'm confident in this release and was very tempted to call it 2.1 Release Candidate 1. I'm not planning on any more changes except bug fixes. All new features are going into 2.2 instead. The scope of the internal changes just made me decide to treat it as a beta for a month before finalizing it.