[
https://issues.apache.org/jira/browse/MATH-613?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13071648#comment-13071648
]
Gilles commented on MATH-613:
-----------------------------
Sorry to be picky but I'm trying that we have a more uniform Javadoc style...
It would help if you please change comments like this:
{code}
* @param a
* the weight of {@code this}
* @param b
* the weight of {@code y}
* @param y
* the vector with which {@code this} is linearly combined
* @return a vector containing {@code a * this[i] + b * y[i]} for all
* {@code i}
{code}
into something like this:
{code}
* @param a Weight of {@code this}.
* @param b Weight of {@code y}.
* @param y Vector with which {@code this} is linearly combined.
* @return a vector containing {@code a * this[i] + b * y[i]} for all
* {@code i}.
{code}
I find the second alternative more legible, and it looks "finished".
I.e.
# Explanation on the same line as "@param". More balance and less "air".
# End sentences with a period. It's more consistent because if you need more
the one sentence, you'll have to add periods anyways.
# Always exactly one space after the "*" character. A big space at the
beginning of a line hinders legibility.
No, there is no document that documents how the documentation should be
formatted. :(
We couldn't agree that it was worth formalizing rules beyond what was
recommended by the Sun guidelines!
> Equivalent of Blas DAXPY
> ------------------------
>
> Key: MATH-613
> URL: https://issues.apache.org/jira/browse/MATH-613
> Project: Commons Math
> Issue Type: New Feature
> Affects Versions: 3.0
> Reporter: Sébastien Brisard
> Priority: Minor
> Labels: linear, vector
> Attachments: MATH-613-20110727.patch
>
>
> In Blas, the method {{DAXPY}} computes an in-place linear combination of two
> vectors. More precisely, a call to {{DAXPY(a, x, y)}} updates vector {{y}}
> with the value of {{a * x + y}}. This can lead to very compact code, which I
> feel the need for in Commons-Math. However, DAXPY also has its limitations.
> For example, it cannot perform the other combination {{y <- x + a * y}}.
> I think it would be useful that {{RealVector}} had a method for computing {{a
> * this + b * y}}, and storing the result in {{this}}. In the spirit of the
> {{mapToSelf}} method, I propose to create two new methods in {{Interface
> RealVector}}
> {noformat}RealVector map(BivariateRealFunction f, RealVector y){noformat}
> and
> {noformat}RealVector mapToSelf(BivariateRealFunction f, RealVector
> y){noformat}
> The former would return a new vector {{v}} such that
> {noformat}v[i] <- f(this[i], y[i])}}{noformat}
> and the latter would update {{this}},
> {noformat}this[i] <- f(this[i], y[i]){noformat}
> Emulating {{DAXPY}} would then simply be a matter of implementing the
> appropriate bivariate function.
> While we are at it, how about
> {noformat}RealVector map(TrivariateRealFunction f, RealVector y, RealVector
> z){noformat}
> {noformat}RealVector mapToSelf(TrivariateRealFunction f, RealVector y,
> RealVector z){noformat}
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira
