Natural Docs 1.2 released
February 19th, 2004
I have some good news, and some bad news.
The good news is that I got some pretty nice new features for you. The bad news is that the best ones are only available for Perl — for now.
What you’ve been using is now called “basic language support.” It’s the explicit documentation only system, and it will always be around because it makes adding new languages very easy, and it’s the only way to handle text files.
What Perl now has, and other languages will be getting in coming releases, is called “full language support.” It requires a custom parser to be written specifically for each language, which is what will make adoption go language by language.
The best feature this gives you is full code documentation. Every class, function, and variable will be detected and automatically added to the documentation, whether you added a topic for it or not. Now you don’t have to manually document everything for the output to be useful, which is especially good if you have an existing codebase and are just starting with Natural Docs. You can turn this off with the -do (--documentedonly) command line option.
Another really nice feature is inheritance diagrams. The current implementation shows the direct parents and children of a class in its output. You can see an example here. However, the architecture is in place for deeper diagrams.
Full language support also brings auto-scoping, so you don’t have to worry about adding section topics to end a class’ scope when you want to document globals. It will also break apart multiple variables declared in the same statement, so if you type “my ($a, $b, %c);”, each one will get its own topic and prototype.
C++, C#, and Java will be the next languages to get full support. After that, I’m open as to which language to hit next. E-mail me to vote for which ones you want to see.
Important! If you added a custom language with NaturalDocs::Languages::Language->New(), you need to change that line to NaturalDocs::Languages::Simple->New() when adding it to 1.2.
But enough about that. What about the features we all get?
First there’s automatic grouping. If you don’t add any group topics to a class, Natural Docs will do it for you. Functions and variables will each get their own headings. Once you add a group manually, though, this turns off completely for that class.
Second, Natural Docs remembers the last command line options you used, so if you change output formats, tab lengths, or anything else that requires all the output files to be rebuilt, Natural Docs will do that for you. You don’t have to remember to use -ro.
That’s it. Sorry there’s not more toys for you non-Perl users, but they’re coming. Again, e-mail me to tell me which languages are most important to you and should get full support sooner.
|Copyright © 2003-2011 Greg Valure|