[MATH] Javadoc for vector methods

[sebb <se...@gmail.com>]

The UnmodifiableVector class contains the following method:

        /** {@inheritDoc} */
        public RealVector add(RealVector w) {
            return v.add(w);
        }

This looks like it would update the vector.
It is only by tracing the code that one discovers that the add()
method takes a copy of the vector first. This does not appear to be
documented anywhere, but perhaps I missed it.

It would be very helpful to include details in the Javadoc of which
methods return copies, and which methods update the current object.

For methods which return an updated object, it is a bug to ignore the
return value.
[cf. String.trim()] It would be nice if there were an annotation to denote this.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org

Re: [MATH] Javadoc for vector methods

[Phil Steitz <ph...@gmail.com>]

On 8/24/11 6:20 AM, sebb wrote:
> The UnmodifiableVector class contains the following method:
>
>         /** {@inheritDoc} */
>         public RealVector add(RealVector w) {
>             return v.add(w);
>         }
>
> This looks like it would update the vector.
> It is only by tracing the code that one discovers that the add()
> method takes a copy of the vector first. This does not appear to be
> documented anywhere, but perhaps I missed it.
>
> It would be very helpful to include details in the Javadoc of which
> methods return copies, and which methods update the current object.

After reviewing the full set of now merged javadoc (thanks,
Gilles!), I could see your point better.  I just committed changes
that try to make things more explicit.  Please review.  Thanks.

Phil
>
> For methods which return an updated object, it is a bug to ignore the
> return value.
> [cf. String.trim()] It would be nice if there were an annotation to denote this.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org

Re: [MATH] Javadoc for vector methods

[Phil Steitz <ph...@gmail.com>]

On 8/24/11 6:20 AM, sebb wrote:
> The UnmodifiableVector class contains the following method:
>
>         /** {@inheritDoc} */
>         public RealVector add(RealVector w) {
>             return v.add(w);
>         }
>
> This looks like it would update the vector.

The name may be a little misleading and even placement inside the
class; but the inherited javadoc is pretty clear:

/**
     * Compute the sum of this vector and {@code v}.
     *
     * @param v Vector to be added.
     * @return {@code this} + {@code v}.

IIRC, we used to have utils classes that encapsulated operations on
linear (and other) objects, but decided to largely dispense with
them in favor of the kind of syntax above -

object.binaryOperation(otherObject) means return the result of
applying the binaryOperation with operands *this and otherObject.  I
personally dislike this style, but it is endemic in OO math
libraries and we have largely adopted it in [math] because it
provides a natural way for operations to be included in the classes
on which they are defined.

So in answer to your question, I don't think anyone would expect
this method to modify either of the arguments once the intent of the
API is understood.

Phil
> It is only by tracing the code that one discovers that the add()
> method takes a copy of the vector first. This does not appear to be
> documented anywhere, but perhaps I missed it.
>
> It would be very helpful to include details in the Javadoc of which
> methods return copies, and which methods update the current object.
>
> For methods which return an updated object, it is a bug to ignore the
> return value.
> [cf. String.trim()] It would be nice if there were an annotation to denote this.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org