Hi,
Currently none of the JSF API classes (interfaces/abstract classes) have
any javadoc in them. I understand that this is due to Sun's copyright
over the actual specification and their refusal to allow that text to
appear in alternative implementations.
This sucks very much, and clearly shows how little Sun understands open
source.
However it sucks even more that the JSF classes distributed by MyFaces
don't have any javadoc and users (like me) must continually reference
the Sun-provided javadoc files for the actual details.
As *implementing* the spec is legal, I would expect that deriving
javadoc from the code (rather than from the spec) would also be legal.
Of course the result is going to be very similar as the code was written
by referencing the specification, and would thus be almost as useful for
MyFaces users as the original spec docs.
What is the feeling from MyFaces developers about patches to add javadoc
to the API classes, where the submitter (eg me) has explicitly derived
the docs from the code rather than the spec? Does anyone feel it's worth
floating this idea on the legal-discuss list?
Here's a proposed disclaimer that could be appended to the class javadoc
for each API class:
/**
* ....docs derived from the code...
* <p>
* <i>Disclaimer</i>
* The official definition for the behaviour of this class is the JSF
* specification and for legal reasons the specification cannot be
* replicated here. Any javadoc present on this class therefore
* describes the current implementation rather than the officially
* required behaviour, though it is believed that this class does
* comply with the specification.
* <p>
* @author ....
* @version ...
*/
Regards,
Simon
