Natural Docs
About
About Natural DocsFeaturesLanguage SupportOutput FormatsDownloadDevelopment
Make a Donation
Supports 19 Languages

Natural Docs is an open-source documentation generator for multiple programming languages.  You document your code in a natural syntax that reads like plain English.  Natural Docs then scans your code and builds high-quality HTML documentation from it.

Current Version
1.52

Natural Docs is stable and ready to be used in real world projects.  Make sure to check the level of support your language has to see if Natural Docs will document all of your code automatically or just what you write for it.

Download
News
Natural Docs 1.52 released
April 21st, 2011

Maintenance release.  If you had trouble with 1.51 freezing or giving you messages about wide characters or Unicode mappings, this will fix it.

Natural Docs 1.51 released
December 21st, 2010

Maintenance release.  There are a number of small bugfixes I won’t go through because most of you probably aren’t running into them, and the people who are were already notified that their changes were going to be in here.

The one I will point out is that Unicode support is improved.  Specifically, Natural Docs supports UTF-16 files now, which some Mac IDEs apparently use.  It seems I’ve bashed Perl’s Unicode support unfairly.  It exists, it’s just annoyingly manual so I have to sniff out the BOM myself and set the encoding accordingly.  I’ve also removed the -cs (--charset) option; Natural Docs always outputs UTF-8 now.  That was just a hack from when I didn’t really know what I was doing on that front yet.

I just looked it up and it was introduced in 1.33 almost six years ago.  And 1.0 was released 7.5 years ago.  Jeez.

Natural Docs 1.5 released
July 22nd, 2010

Hey look at that, I’m not dead... again!  First the features, then an update on the project.

The biggest new feature is the addition of syntax highlighting.  Both prototypes and (start code) segments will be highlighted via the integration of Google Prettify.  You can turn this off or extend it to >, :, and | prefixed lines with the -hl command line option.

You can also use named links instead of just raw URLs and e-mail addresses.  This is done with the “at” keyword, which was chosen because it often fits right into the sentence and leaves the source readable: “Visit the <web site at http://www.naturaldocs.org>” becomes “Visit the web site” in the output.

The licensing has been changed.  Natural Docs has moved from version 2 of the GPL to version 3 of the AGPL.  I was planning to do this with 2.0 and leave 1.x alone, but Prettify’s Apache license wouldn’t be compatible otherwise so 1.x gets it too.  I’ve also updated the license text in numerous files to make explicit what I thought was always assumed: any generated documentation you create is your own and not subject to the GPL.  The JavaScript and CSS files bundled with it are still part of Natural Docs, but their licensing doesn’t apply to the documentation as a whole.

A bunch of minor bugs are fixed as always, but I’m not going to go through them except for one.  Natural Docs will now handle files with classic Mac line breaks, which some IDEs apparently still use.  This is more of a problem with Perl sucking than Natural Docs, but I’ve successfully worked around it.  Perl still chokes on UTF-16 files though.

So anyway, on to the project as a whole.  I’ve actually been sidetracked with a different project for the better part of the past year so no real progress has been made in that time.  Now that that’s come to a close I’m ready to get back into it.  I’m still going to be dedicating most of my time to the C# version because all the old reasons still apply: the engine needs an overhaul and I can’t imagine doing it in Perl.  However, unlike before I’m going to occasionally drop back into the Perl code instead of just letting it languish.  If there’s a feature that works into the existing architecture easily I’ll add it, and I might backport a few from 2.0.

1.5 illustrates this well.  Prettify was something that was fairly easy to tack on.  A native highlighter would have been better but isn’t worth the effort at this point.  Named links were backported from 2.0 because they fit into the architecture easily.  And Perl’s inability to handle Unicode and cross-platform line breaks transparently is another example of why it’s better to switch to something more modern.  It wouldn’t be a deal breaker on its own but I have many such examples.

So that’s it for now.  People occasionally ask me when 2.0’s coming I don’t have an answer.  Time isn’t as plentiful as is was years ago when I started Natural Docs and didn’t have a real job yet.  I’ve been sneaking it in where I can, and actually having some time away from the work I’ve already done has been good for me.  While reacquainting myself with the code I got a fresh look at it and saw where it could be better.  The continued evolution of Mono during that time means I can take advantage of newer language features.  And the other project increased my knowledge of JavaScript considerably which bodes well for what I can do with the output in the future.

Copyright © 2003-2011 Greg Valure