In fact, I'd go as far as saying that in cases, it makes things worse. Leading on from the above, sometimes the usage of markup tags (so that Doxygen realises that something it wants is present) actually adds a lot more visual noise, without contributing that much to readability. This is information that should already be available to the documentation engine when it reads the file (how else does it see the stuff inside? Telepathic inference?! Wire tapping?!), which it should be able to easily make use of.Īdmittedly though, the \ingroup tag is something that needs a bit more thought for now about what should be done about it, though it's likely that this approach is still too heavy handed.ĭoxygen Flaws - Needless markup which creates visual confusion The \file tag should really not exist, just like the irritating $Id:$ keyword expansion tags that CVS popularised and drilled into the minds of some SVN refugees (for the record, I believe that these are more of a nuisance than useful, and I do not support the addition of this sort of tagging to files). */As you can see, this has been taken from a source file in the Blender source code, post-Doxygen-module-tagging. ** \file blender/editors/animation/keyframes_general.c For example, the following toplevel tags are fundamentally braindead: Secondly, there is a lot of IMO needless markup syntax, which perhaps is necessary for the parsers used there to make themselves useful. Having implemented a few parsers already, I can say that I understand why this implementation was chosen, though I don't believe that with a more intelligent implementation, the same can't be achieved.ĭoxygen Flaws - Needless markup and syntax rather, they need to be started with a double-tag, for example in C: However, these are not ordinary comments. However, while I'm not going to dispute the value of such documents (though IMO they should not be a crutch upon which bad code can be hung), I do take issue with some of the details of their workings, in particular, the syntax they use.ĭoxygen Flaws - Ugly Double-tag commentsįirst things first, Doxygen/Javadoc work by parsing the contents of comments in the source file. Another one, though more language antagonistic, is "JavaDoc", which is Java's assimilated dialect of Doxygen-ism. One of the most popular ways to do so is using a tool called "Doxygen", which I believe was popularised by the C++ community for whom such a tool is probably strictly necessary to get a grip on the codebases involved (and which also mandated the creation of UML and other such tools/methodologies which are highly considered by software engineers). Documenting how things work is quite important, especially in environments where collaborative work is involved (such as software engineering) or when other people who were not involved in the development later need to use it.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |