Re: Interest in new XML format for Doxygen export

The old XML format would still be there; I didn't want to break anyone
who might be using it, and it made a good template to match my results
against.

There are several problems with the old XML format that made it
difficult to use. Or, rather, difficult to use when attempting to
generate non-Doxygen-like documentation.

First, there are repeats of information. For example, if you mark a
function as virtual, there will be an attribute named virtual, but the
return type will also include the word "virtual". This makes it
difficult to not include that word if you wish to, in the final form
of the docs, move that word elsewhere.

Second, the general structure of the documentation mirrors Doxygen
rather than a more presentation-neutral format. As an example, public,
private, etc members are all added to member groups in DoxygenXML.
Having an XSLT processor to automatically generate these member groups
would be trivially easy, but it now become harder to "ungenerate" them
if you wish to order the members in some other way.

Third, there are certain... issues with regard to the ownership of
various members. Does the file own them (and therefore have the
documentation for them)? Does the namespace? Does a Module? Where a
documented member (that has no class) lives is not easily determined.
This means that an XSLT that need to, for example, generate a list of
all members, or all global members, or all members of some scope,
needs to do a lot of work. It has to look in files, namespaces, and
Modules before it can be sure it hasn't missed something. Of course,
if your output documentation looks Doxygen-like (with output pages for
each), this isn't a problem. But if it doesn't...

Lastly, a lot of the naming makes it difficult to present the name of
an object in the way you want rather than the way Doxygen wants. For
example, the name of a class is its fully-scoped name. This is
needless, because an XSLT can easily generate a fully-scoped name from
just the containment hierarchy and the short-name of an object.
However, an XSLT cannot easily generate a short-name (text parsing is
not XSLT's strong suit) from the fully-qualified name.

So, I rewrote the format entirely.

Under the new format, all documented language elements (classes,
namespaces, members) live in their own section. This section
structurally mirrors the containment defined by the organization of
the source code. There is an explicit global scope, for example. This
global scope holds all global classes, namespaces, and members.
Namespaces can hold namespaces, classes, and members, while Classes
can only have other classes and members.

Modules and files are merely documented elements with a list of
references to the other documented language elements. And Pages are
just blobs of documentation without any references whatsoever (well,
no list of them rather. They can still have textual references in the
documentation).

On 11/29/06, Dimitri van Heesch <[email protected]> wrote:
> Hi Jason,
>
> Please let me know. I'm interesting in what it looks like and why you need it.
>
> Regards,
>   Dimitri
>
>
> On 11/28/06, Jason McKesson  <[email protected]> wrote:
> > I am currently working on exporting a new XML format from Doxygen. I was  wondering if there would be some interest in integrating this into the  main line when it is finished.
> >
> > If you want more details about how this format differs from the current  Doxygen XML format, please let me know.
> > -------------------------------------------------------------------------
> > Take Surveys. Earn Cash. Influence the Future of IT
> > Join SourceForge.net's Techsay panel and you'll get the chance to share your
> > opinions on IT & business topics through brief surveys - and earn cash
> > http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
> >
> > _______________________________________________
> > Doxygen-develop mailing list
> > [email protected]
> > https://lists.sourceforge.net/lists/listinfo/doxygen-develop
> >
> >
> >
>
>

-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys - and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV