Name: gm110360 Date: 05/12/2004


A DESCRIPTION OF THE PROBLEM :
In the method documentation for javax.xml.xpath.XPath.evaluate( String, Object,
QName), the possible return types (the static types to which a caller would
cast the result of a call) are not specified.

The return value description says:

   Returns:
       Result of evaluating an XPath expression as an Object of returnType.

Saying "Object of returnType" would only be valid if returnType were of type
java.lang.class, but it is not.


The returnType parameter description says only:

   returnType - The desired return type.

That refers (ambiguously) to the logical XPath type, but doesn't specify any
physical Java type.

The method description does refer to XPathConstants. However,
XPathConstants' documentation says nothing about the correspondence
between XPath types and Java types (e.g., XPath's STRING and Java's
java.lang.String, or XPath's NODESET and Java's um...well...the
documentation doesn't say).


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
The XPath.evaluate(...) description should have specified the correspondence between the XPathConstants values (or XPath types) and the corresponding
Java subtypes of Object (or should have pointed to some other class's
description that specified that correspondence).

In general, the documentation should have have provided enough
information for the reader to know to what static type the return value
could be cast to to for each case.



ACTUAL -
See the Description section.

URL OF FAULTY DOCUMENTATION :
http://java.sun.com/j2se/1.5.0/docs/api/javax/xml/xpath/XPath.html
(Incident Review ID: 265225)
======================================================================