About Natural Docs

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.

Background

When I first started Natural Docs I just needed something to make an API reference for a different project I was working on.  I didn't like the other tools I looked at at the time.  Most made me feel like I was writing more code and the generated documentation was just another compilation target.  I would write it and compile it and check the HTML to make sure it looked right.  That really limited how useful the comments were to me as I was coding and it seemed unnecessary to write this way.  I eventually found another product that had a much cleaner syntax, but it had other serious flaws so I gave up and decided to write my own in Perl.

The other project I was working on didn't pan out but I thought the documentation generator was still pretty useful, so I open sourced it and published it as Natural Docs.

I continue to use it with almost everything I work on and continue to think I had the right idea.  Documenting has also become an integral part of my coding process instead of just an afterthought.  The comments should be for you as much as they are for other people, and by having them read easily you don't have to switch to the generated documentation for the things right in front of you, which helps you keep your focus.  It also makes it easier to update as you work, making the result a living architecture document that evolves with your project.

Not all projects are large and complicated enough to need a documentation generator.  Self-documenting code is still the ideal, but sometimes complexity is unavoidable.  Once you've worked on a project large enough where you can work on one section for a while, finish it, and then have to change it six months later and not remember how it works, you see the value.

Natural Docs is more than just its comment style though.  I wanted the output to be high quality HTML.  I wanted all the documentation's features to work from my hard drive so I could keep a private copy while I work.  I wanted the build process to be differential so it's fast enough to update often.  When I'm working I keep it open, and when I need to I just hit a keystroke to run Natural Docs again, wait a few seconds, and refresh the browser.

Over the years Natural Docs picked up new features like full language support and Javadoc compatibility.  It eventually outgrew Perl and some of the architecture decisions I made when I first designed it.  Natural Docs 2.0 is a complete rewrite in C#, with new features and a new engine that has room to grow and do some things it couldn't before.  I hope you like it.

The Author

Natural Docs is written by Greg Valure (gregv[xxx]alure @ natural[xxx]docs.org).  It's free, but if you find it useful and have some money to spare, check out the donation page.  It's not what you think it is :)

Who Uses It

Natural Docs is used by people all over the world.  I know of people who use it in educational institutions, government, companies (including many well-known ones) as well as individuals who just want to use it for their own projects.  Though by far the coolest place it was ever used was to aid in the development of a Mars orbiter!

You can find some public generated documentation by searching for "Generated by Natural Docs".  Natural Docs 2.0 was just released in August 2017 so many examples may still be using the old version.