Traps No program is without its limitations. These are the things you have to watch out for when using Natural Docs. - Don’t break comments. A topic must be contained in a single continuous comment. This isn’t a problem with multi-line comments, such as
/* and */ in C++, but when stringing together single-line comments, such as // in C++ and # in Perl, blank lines in your documentation must start with the comment symbol too to keep it continuous. - Blank comment lines are part of the syntax. To start a new topic, create a header, or go back to regular text after a bullet or definition list, you need to first skip a line in the comments. They will not work otherwise. Also, if your comment symbol is #, make sure there is a line between the first comment and the shebang (#!) line.
- Be aware of the package limitations. Currently, when documenting packages and classes you must use their full name, such as “A::B::C” and not just “C”. On top of that, links to them must be fully resolved (“A::B::C”) and links to their members must be either fully resolved (“A::B::C::Member”) or local (“Member”).
- If you only have basic language support, Natural Docs doesn’t detect where classes end. When you create a class topic, every topic appearing after it in the file until the next class or section topic is considered part of that class. This normally will not cause problems, but if you need to document globals that appear after a class in a file, add a section topic between them. That will end the class’ scope. You don’t have to worry about this if you have full language support.
- Topics are case-sensitive, even if the language is not. Make sure you use consistent capitalization in your documentation or you will not be able to link between symbols easily. Make sure the topic title’s case matches the function or variable name or its prototype will not be included.
- Text files still need topic keywords. When using .txt files, you still need to start with a “keyword: title” line for every topic.
- Natural Docs HTML is not Netscape 4 compatible. Sorry, I’ve long given up on trying to support Netscape 4. It’s not so much that it can’t do certain things, it’s that it tries to do them anyway and fails miserably. I’m not going to try to bludgeon the code into something that will look respectable in Netscape 4 because it would be a major effort and very few people use it anymore.
- Natural Docs won’t preserve formatting or comments in the menu file. This is actually the flip side of a feature. Natural Docs rebuilds the menu file’s indentation and comments when it’s run, which allows people to do quick and dirty editing without the file becoming unreadable. However, this will also cause any manual formatting or comments you added to be lost.
|