[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [cdt-core-dev] Another Parser Document
|
Alain Magloire wrote:
P.S. Yes, I have seen the various suggestions that Eclipse use Doxygen
for doc generation, but I'm not convinced. While I've used Doxygen a lot
and greatly appreciate the work Dmitri has put into it, I also feel that
its architecture is too monolithic and too reliant on an ever-increasing
rats'-nest of config options. Also, the frankly bizarre dependency on Qt
even for the core command-line app is always going to be a portability
headache. I suspect that using the CDT parser for input, vanilla XML as
intermediate representation and XSLT/XSL-FO/Batik for output (maybe
pinching some components from Eclipse GEF for class diagram layout),
could cover 90% of the functionality required by a JavaDoc equivalent.
Probably true, but doxygen is widely use in GNU distributions and
other packages. Would you be interested in starting doxygen support
part of cdt-contrib plugins effort or you are saying to reinvent
the will will yet another document marking ?
There are two separate "wheels" here: Doxygen the program, and the
installed-base of C++ code containing doc comment markup targetted at
that program. The inertia you allude to comes from the second of these,
not the first.
Doc comment syntax, like just about everything else C++-related, is
hopelessly fragmented. Doxygen supports both JavaDoc-style and Qt-style
doc comments, and has steadily added and deprecated syntax over the
years; Doc++ does something slightly different; I think Synopsis does
something else again; people coming from VC7+ may have Microsoft's
XML-style doc comments in their code.
Obviously, nobody is about to invent the doc comment syntax to end all
doc comment syntaxes, but I don't think anyone needs to. I see no reason
why a doc tool should depend on a particular markup syntax, or vice
versa. The meat of a doc tool is understanding the documentable
declarations in code (parsing), and resolving crossreferences to other
decls mentioned in the declaration or its comment (indexing). Markup
syntax is one of the most trivial aspects of a doc tool, and ought to be
configurable and extensible outside of the tool, IF the tool's output is
a "dumb" representation like XML. It's Doxygen's insistence on
controlling the entire workflow that makes it so inflexible.
Example: suppose I want to add an "invariant" block to my class
comments, and suppose that Doxygen didn't support this. (I think it does
now, but it hasn't always. Look at the Doxygen change history and wish
list; this sort of thing happens all the time.) The program should not
be the bottleneck here. "Standard" markup tags are useful, especially
for entities that will be crossreferenced, but I should also be able to
have a standard config rule that says "custom doc comment sections are
in the form @@KEYWORD{...}", add "@@invariant{foo must be greater than
bar}" to my class comment, have the doc tool spit out XML like
<class name="MyClass">
<otherstuff/>
<invariant>foo must be greater than bar</invariant>
</class>
and write my own stylesheet to format that <invariant> tag however I
like, without the doc tool ever having to know or care what an
"invariant" is.
Okay, I got sidetracked there. My point, I think, is that a doc tool
which isn't Doxygen does not require everyone with investments in
Doxygen-style doc comments to tear them up and rewrite them. It should
be possible to reinvent the wheel without also reinventing all the roads.
