commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <phil.ste...@gmail.com>
Subject Re: [MATH] Javadoc for vector methods
Date Wed, 24 Aug 2011 19:44:35 GMT
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


Mime
View raw message