[dbdoclet] Re: Problem with @link, xreflabels and sorting

Hello,

thank you for your bugreport.

> (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.

Will be fixed as soon as possible.

> (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.

A command line argument -noxreflabel to suppress the generation of xreflabels 
should help, or?
 
> (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.

Very interesting feature. I will think about it when the support for jdk 1.5  
(annotations, generics, enums, varargs, ...) is finished.

Regards
Michael

Other related posts: