New HTML Output

Natural Docs' HTML output was completely redesigned. You don't have to do anything to get it except run the new version on your project. You can use this example output if you want to explore or follow along while we walk through what's new.

File and Class Views

The first thing you'll notice is that there are separate file and class views. There's also a third database view but that will only appear if you use the database keywords.

The file view now matches the source tree exactly instead of being a simplified version of it. Parent folders stack up instead of having the children expand inline, since that didn't work so well when you got many levels deep.

People have been wanting a class view for a long time, and particularly the ability to combine multiple source files into a single page, so here it is. The menu is organized by the namespace, and if you use multiple languages in your project it will be organized by language and then by class so they don't get mixed together.

Here you can see the files in Engine\Source\CodeDB and the corresponding CodeClear.​NaturalDocs.​Engine.​CodeDB classes. Notice the SQL was broken out into separate source files but they're combined back into a single class page.

Three Panel Design

Now we're getting somewhere! The output in Natural Docs 2.0 uses a three panel design. The file or class menu is on the left, then the summary of the page, and then the page content itself. In Natural Docs 1.x the menu and summary would scroll away as you moved down the page. Even if you used the framed HTML format the summary would still go. In 2.0 all three stay in place and scroll independently so the summary is always available to help you navigate the page.

You can drag the borders to resize them too. Notice how long names like CodeClear.​NaturalDocs.​Engine.​CodeDB.​Accessor intelligently wrap in both panels, and the left menu tabs expand and contract.

The only downside is there's no room for the first line of text in the summary anymore. But that's okay because if you hover over them you'll get not only the prototype, but the entire first paragraph of text.

Another thing you might notice is there's a color swatch next to every code element that matches its prototype color. This helps you sort through them visually.

Better Prototypes

Something you may have noticed in the earlier screen shot is that the parameter types appear not only in the prototype but in the body as well.

This is completely automatic. All you need to do is document the parameters in a definition list under a "Parameters" heading (or "Params", "Arguments", etc.) which you were probably doing already, and Natural Docs will look it up in the prototype and display the types for you. If the type is documented it will be a clickable link with a tooltip as well.

Documented types are also clickable in the prototype. Natural Docs links are normally red but that was already being used by the syntax highlighting, so to see the links just move your mouse over any part of the prototype and they will all underline. I felt this was a good compromise between not having to mouse over every type to see if it's a link and not having the underlines there permanently which looks ugly and doesn't fit with the rest of the style.

Prototypes also automatically switch between a wider and narrower format depending on how much room you have on the screen.

More Inheritance Diagrams

Natural Docs 1.x had class inheritance diagrams but only if you had full language support, which was limited to C#, Perl, and ActionScript. Natural Docs 2.0 can build inheritance diagrams even if the language only has basic support, so long as the classes are documented and use a C++ or Java-like inheritance syntax.

That means the syntax would have to be similar to "class A extends B", though it will also accept keywords like "inherits", "implements", "base", or just a colon like C++.

I also wrote custom parsers for Python and Ruby, so even though their syntax is different and they don't have full language support yet, Natural Docs will still be able to build inheritance diagrams for documented classes. This doesn't apply to modules with mixins in Ruby though, that will still need full support.

As you can see above, the class prototypes will also show attributes like "public" and "abstract".

Better Search

Search is featured much more prominently by being in the page header. Classes appear in bold, and other results include color swatches to help tell you what type they are, just like in the summary. Multiple results with the same name are collapsed under expandable headings, and you can navigate all the results with the keyboard. Also, just like in Natural Docs 1.x, search works regardless of whether you're viewing the documentation on a web server or just opening it from your hard drive. There's no software to install, the generated HTML files are enough.

Next: New Comment Features