[dbdoclet] Problem with @link, xreflabels and sorting

Hello,

I have just replaced our proprietary docbook generator with dbdoclet.
Three issues have come up:

(1) This should be considered a bug: ... {@link SomeClass
<code>SomeClass</code>} ... is transformed to "<code>SomeClass</code>".
Obviously dbdoclet assumes that the second argument to @link is to be
copied literally. But actually it can be anything that you want to make
part of the HTML anchor. Thus it can, of course, include HTML markup,
which should be transformed to docbook by dbdoclet.

(2) dbdoclet generates xreflabels for the packages, classes etc. This
causes docbook to use these labels when the items are referenced. This
may or may not look good.

While "... see SomeClass[123] ..." is acceptable, "... see
getProperty()[456] ..." has too little information. There are several
approaches to this. References to methods could be improved by adding
the class to the method name, i.e. "... SomeClass.getProperty()[456]
...". But I would prefer the possibility to suppress the generation of
xreflabels completely. Then I get "... see Section 3.4 "SomeClass" [456]
..." as for all my other xrefs.

Of course I looked into the docbook stylesheets. There is a template
that handles xrefs to nodes with xreflabels, but this template does not
get the referenced node passed as argument, so it is hard (though
possible) to fix this there.

(3) We want the generated JavaDoc to be "readable" (we generate an API
documentation). Readability suffers a lot if the classes have no logical
ordering, e.g. derived interfaces after the interface they are derived
from. While I could re-establish some ordering on the package level with
a postprocessing stylesheet (as there is nothing else on the package
level), re-ordering classes within the packages based on Reference.xml
is not an easy task. Our proprietary doclet therefore had the possibilty
to specify a precedence list. Packages and classes are sorted before
processing: items with fully qualified names starting with entries in
the list take precedence over items not found in the list. Two items
with qualified names having (partially) matching entries in the list are
sorted according to the entries position within the list.

So if you have a sort list "a.b, a.b.S, a.c.f", package "a" will be
processed before any other package, package "a.b" will be processes
before "a.c" but "a.b" will be processed after the others. Within the
package "a.b", class "a.b.S" will be output first.

Regards,

    Michael

Other related posts: