Javadoc for the JSF API classes

[Simon Kitching <sk...@obsidium.com>]

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

Re: Javadoc for the JSF API classes

[Martin Marinschek <ma...@gmail.com>]

You can change that from

..it is believed that this class does comply with the specification...

to:

...this class officialy complies to the specification.

What have we passed the TCK for, if not for this ;) ?

Yes, if you want to put efforts into this, you are heartily welcome to
do so... It's not a question for legal at all if you derive it from
the code and don't copy it over from the SUN doc.

regards,

Martin

On 11/18/05, Simon Kitching <sk...@obsidium.com> wrote:
> 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
>


--

http://www.irian.at

Your JSF powerhouse -
JSF Consulting, Development and
Courses in English and German

Professional Support for Apache MyFaces