tags:

views:

73

answers:

2

In the javadocs some APIs (outside java.lang and java.util) the "Use" section is missing.

XMLStreamReader for example. It is a bit unpleasant that you can't tell what classes of the API return the class that you need, based on the javadoc, and you must employ some other tricks (like IDE features) to do this.

Is there any reason for not including the "Use" section in these APIs?

+1  A: 

Classes like javax.xml.stream.XMLStreamReader are part of Java extension mechanism, so they can be replaced with specific implementations (in this case, if I recall correctly, an implementation of stax).

You are supposed to get the actual service class via a factory method, by using the two public classes XMLInputFactory and XMLOutputFactory. It is by design that you don't need to know what is the actual implementing class.

EDIT: The link that you provided for XMLStreamReader is from the web-services pack for java 1.5. I don't know why the use section is missing, but for whatever its worth, in java se 6 api it is included (see here). Hope this helps ...

Yoni
Yes, but use _within the API_ is particularly useful. The "see also" section is often useful, but not always. And XMLStreamReader is part of the boostrap classes - it's in rt.jar
Bozho
can you please provide a link with example? Perhaps I misunderstood what is the "use" that you are referring to.
Yoni
http://java.sun.com/javase/6/docs/api/java/util/class-use/List.html
Bozho
+1  A: 

The link you posted for XMLStreamReader was for javadocs under http://java.sun.com/webservice, rather than for the core JavaSE API.

The javadoc for XMLStreamReader in the core javadoc, however, does have the "Use" section fully populated.

As to why they are different, I suspect it's just a quality control issue.

skaffman