QDox

• Type: Improvement
• Status: Resolved
• Priority: Major
• Resolution: Cannot Reproduce
• Affects Version/s: 1.5, 1.6, 1.7
• Fix Version/s: None
• Component/s: Java API
• Labels:

  None
• Environment:

  Windows 2000, jdk 1.4.2, ANT 1.5.4, Eclipse 3.0 / 3.1M4, QDOX: 1.5 as well as cvs-checkout.

Description:

At parse-time, when the JavaSource Object is created by the JavadocBuilder > (ModelBuilder <> parser), the URL member of the JavaSource (source) is not set. This is due to the chaining:

addSource(File file){
-> addSource(URL url){
-> addSource(Reader reader, String sourceInfo){
}
<aJavaSource>.setURL(url);
}
}

Problem:

A custom DocletTagFactory (constructor) may be used to parse for Annotations. It might be very useful to report syntax-errors from this custom parser. But these reporting is useless, when no information about the current url being processed is at hand. The DocletTagFactory or the triggered custom parser cannot access that information. The sourceInfo String is provided for the qdox parser's exception reporting, but that information is not available for the DocletTagFactory as well. Throwing an Exception would be a way of bringing the file name to the console, but warnings or debugging should not terminate the application.

Suggestion:

Medium change of the API:

Strip the creation of the JavaSource Object out of the ModelBuilder. Feed the ModelBuilder with a JavaSource instance (replace no-arg Constructor and extend the 2nd) that is already initialized with the URL.

Within JavadocBuilder:

change
addSource(Reader reader, String sourceInfo)

to
addSource(Reader reader, JavaSource source)

and declare it private (delegation only).
The code will then look like:

ModelBuilder builder = new ModelBuilder(
classLibrary,
docletTagFactory,
source
);
...

remove
addSource(Reader reader)

change code of method:

addSource(URL url){
JavaSource source = new JavaSource();
source.setURL(url);
addSource(new InputStreamReader(url.openStream(),encoding),source);
return source;
}

Ok, ok, I completely have no clue about the side effects of this suggested refactoring. But would be pleased, if you do.

BTW: Great work, really. I used xjavadoc and switched to QDox. Similar API, same author, improved from scratch.

Achim

• Assignee:

  Robert Scholte

  Reporter:

  Achim Westermann

• Created:

  28/Jan/05 3:48 PM

  Updated:

  25/May/11 3:59 PM

  Resolved:

  25/May/11 3:59 PM