News
Natural Docs 1.22 released
March 14, 2004
Big bugs and big features. First the fun stuff.
Full language support has been added for C#. It gets all the spoils that come with it: full code documentation, class hierarchy diagrams, and auto-scoping.
I discovered to my initial chagrin that C# allows relative identifiers when specifying parents. That support has been added, so as a result, everyone can now use relative links. So if you’re in class A.B.C and have a link <X>, it will first try to resolve to A.B.C.X, then to just X like before. But now it will try to resolve to A.B.X and A.X as well. It happens in that order, with global coming before relative, so that you can completely ignore this feature if you want, plus you don’t have to worry about the links in your current documentation getting messed up.
Note that as a side effect to this, the HTML page anchors will have changed if you use anything other than a dot separator. What was previously #Package::Package.Function will now be #Package.Package.Function. This is only important if you linked to specific topics from outside your documentation.
A few people didn’t like the auto-grouping, so you can now control it with -ag (--autogroup) on the command line. The options are “full”, which is the behavior you’re used to, “basic”, which only does functions, variables, and properties, and “off”, which does nothing at all.
Finally, I added more topic keywords. Constructor and Destructor for functions, Namespace for classes, and UInt, Short, UShort, Long, ULong, Byte, UByte, SByte, Decimal, Real, WCharacter, WChar, WString, and WStr for variables.
The bigger the changes, the more likely they are to introduce bugs. 1.2 was no exception.
The dreaded “Files” bug is fixed. If the first topic in a file is “File: ...”, “Script: ...”, or something similar, 1.22 will handle them correctly again.
Multiline prototypes in Pascal and Ada work again, as well as Pascal prototypes with directives. Support has been added for prototypes in Oracle 8.1’s object oriented option pack.
Yet another Perl parser bug was fixed. The things that trip it up are getting more and more obscure, so it should be becoming increasingly rare that anyone will run into problems with it. Also, blank pages won’t be generated occasionally when using Perl with -do.
Fixed a bug where the full path names were appearing in the index, and sometimes as part of the title. This actually started with 1.16.
That’s all. You can still e-mail me to vote for which language you want to get full support next. C++ and Java will come first, then it’s wide open.
Natural Docs 1.21 released
February 23, 2004
Bug fixes already. Oh well.
Fixed a few bugs in the Perl parser, mostly related to certain regular expressions, ?: statements, and -s statements. If you’ve had the automatic documentation or the prototypes for the explicit documentation stop before reaching the end of the file, this should fix it.
In minor feature news, the topics used for automatic grouping are now controlled by NaturalDocs::Topics, so those of you with custom topic types can take advantage.
Also, properties are now separate from variables. If you documented something with “prop” or “property”, it will have its own index and probably have a correct prototype if it didn’t before.
Natural Docs 1.2 released
February 19, 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.