On 1/22/08, [EMAIL PROTECTED] <[EMAIL PROTECTED]> wrote:
> I am removing as much checkstyle error as possible in preparation of 1.2
> release. The current errors all deal with missing javadoc tags in derived
> classes of the stat subpackages. A typical example is:
>
> /**
> * @see
> org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getResult()
> */
> public double getResult() {
> // some implementation
> }
>
> I have started removing them by copying the javadoc from abstract base class
> or
> interface as needed, because I thought we should avoid the [EMAIL PROTECTED]
> doc for
> the sake of java 1.3 compatibility (the tag as been introduced in java 1.4 if
> I
> remember correctly). However, the current versions of
> o.a.c.math.stat.descriptive.moment.Variance and
> o.a.c.math.stat.inference.ChiSquareTestImpl classes already use [EMAIL
> PROTECTED] I
> think this is an error, but since it is much better than copying the javadoc,
> I
> wonder if this should be generalized or fixed. Do we intend to be java 1.3
> compatible up to javadoc tags ?
>
This is a painful topic, as there is quite a bit of fairly complex
javadoc that would have to be copied everywhere to make checkstyle
happy. I do not like the idea of maintaining multiple copies of this
content. From time to time errors are reported in the javadoc and
fixing them when we have copies all over the place is not easy.
There are really two questions here.
1) Do we copy javadoc from interface to implementation, or to utils classes?
2) Is it OK to use [EMAIL PROTECTED] when we want the generated javadoc to
have some content added for the implementation.
We have not been consistent on 1). The argument for it is that it
makes the *code* easier to read and as a side-effect, makes checkstyle
happier.
Regarding 2), I think it is fine. IMO, our 1.3 compatibility
commitment is to compile and run the code and tests. Users should be
able to a) load and run classes from our binary jars under 1.3 b)
compile sources and successfully run tests under 1.3. I do not see
javadoc or site generation as within scope. Others may disagree on
this.
1) is especially hard for things like TestUtils (which I was just
puzzling over last night) where the @see tags point at the definitive
API doc. I was trying to find a way to get the javadoc tool to gen
this content, but I don't think it is possible. Would appreciate any
ideas on how to do this.
Phil
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
