[jira] [Created] (MATH-674) Too much documentation in "UnivariateRealFunction.java"?

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

[jira] [Created] (MATH-674) Too much documentation in "UnivariateRealFunction.java"?

Gilles (Jira)
Too much documentation in "UnivariateRealFunction.java"?
--------------------------------------------------------

                 Key: MATH-674
                 URL: https://issues.apache.org/jira/browse/MATH-674
             Project: Commons Math
          Issue Type: Improvement
            Reporter: Gilles
            Priority: Trivial
             Fix For: 3.0


I noticed that because they inherit the Javadoc for "UnivariateRealFunction", all functions in package "o.a.c.m.analysis.function" have their "value" method contain a fairly large amount of documentation that is related to a marginal issue (advice about why and when a user would need to implement his own exceptions for his own functions) _that does not apply to the function being documented_.
It might be confusing to have that documentation appear there (i.e. in a place where none of the functions are defined by the user). It should probably be moved elsewhere (user guide).


--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira

       
Reply | Threaded
Open this post in threaded view
|

[jira] [Commented] (MATH-674) Too much documentation in "UnivariateRealFunction.java"?

Gilles (Jira)

    [ https://issues.apache.org/jira/browse/MATH-674?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13109774#comment-13109774 ]

Sébastien Brisard commented on MATH-674:
----------------------------------------

I think it is valuable piece of information that should remain in the javadoc. How about moving it to the header (interface comment) of {{UnivariateRealFunction}}?

Also, is there a reason why
  * those classes should not be final? In the improbable case someone would reimplement eg Abs, it would probably be better to re-derive it from {{UnivariateRealFunction}}
  * the singleton pattern should not be used for these very basic functions?


> Too much documentation in "UnivariateRealFunction.java"?
> --------------------------------------------------------
>
>                 Key: MATH-674
>                 URL: https://issues.apache.org/jira/browse/MATH-674
>             Project: Commons Math
>          Issue Type: Improvement
>            Reporter: Gilles
>            Priority: Trivial
>              Labels: documentation
>             Fix For: 3.0
>
>
> I noticed that because they inherit the Javadoc for "UnivariateRealFunction", all functions in package "o.a.c.m.analysis.function" have their "value" method contain a fairly large amount of documentation that is related to a marginal issue (advice about why and when a user would need to implement his own exceptions for his own functions) _that does not apply to the function being documented_.
> It might be confusing to have that documentation appear there (i.e. in a place where none of the functions are defined by the user). It should probably be moved elsewhere (user guide).

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira


Reply | Threaded
Open this post in threaded view
|

[jira] [Commented] (MATH-674) Too much documentation in "UnivariateRealFunction.java"?

Gilles (Jira)
In reply to this post by Gilles (Jira)

    [ https://issues.apache.org/jira/browse/MATH-674?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13113515#comment-13113515 ]

Gilles commented on MATH-674:
-----------------------------

bq. How about moving it to the header (interface comment) of UnivariateRealFunction?

+1

bq. those classes should not be final?

I don't see any drawback. Are there obvious advantages?

bq. the singleton pattern should not be used for these very basic functions?

Why?


> Too much documentation in "UnivariateRealFunction.java"?
> --------------------------------------------------------
>
>                 Key: MATH-674
>                 URL: https://issues.apache.org/jira/browse/MATH-674
>             Project: Commons Math
>          Issue Type: Improvement
>            Reporter: Gilles
>            Priority: Trivial
>              Labels: documentation
>             Fix For: 3.0
>
>
> I noticed that because they inherit the Javadoc for "UnivariateRealFunction", all functions in package "o.a.c.m.analysis.function" have their "value" method contain a fairly large amount of documentation that is related to a marginal issue (advice about why and when a user would need to implement his own exceptions for his own functions) _that does not apply to the function being documented_.
> It might be confusing to have that documentation appear there (i.e. in a place where none of the functions are defined by the user). It should probably be moved elsewhere (user guide).

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira

       
Reply | Threaded
Open this post in threaded view
|

[jira] [Commented] (MATH-674) Too much documentation in "UnivariateRealFunction.java"?

Gilles (Jira)
In reply to this post by Gilles (Jira)

    [ https://issues.apache.org/jira/browse/MATH-674?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13113891#comment-13113891 ]

Sébastien Brisard commented on MATH-674:
----------------------------------------

Got it. Sorry about that,
Sébastien

> Too much documentation in "UnivariateRealFunction.java"?
> --------------------------------------------------------
>
>                 Key: MATH-674
>                 URL: https://issues.apache.org/jira/browse/MATH-674
>             Project: Commons Math
>          Issue Type: Improvement
>            Reporter: Gilles
>            Priority: Trivial
>              Labels: documentation
>             Fix For: 3.0
>
>
> I noticed that because they inherit the Javadoc for "UnivariateRealFunction", all functions in package "o.a.c.m.analysis.function" have their "value" method contain a fairly large amount of documentation that is related to a marginal issue (advice about why and when a user would need to implement his own exceptions for his own functions) _that does not apply to the function being documented_.
> It might be confusing to have that documentation appear there (i.e. in a place where none of the functions are defined by the user). It should probably be moved elsewhere (user guide).

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira


Reply | Threaded
Open this post in threaded view
|

[jira] [Resolved] (MATH-674) Too much documentation in "UnivariateRealFunction.java"?

Gilles (Jira)
In reply to this post by Gilles (Jira)

     [ https://issues.apache.org/jira/browse/MATH-674?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Gilles resolved MATH-674.
-------------------------

    Resolution: Fixed

Revision 1175588.

> Too much documentation in "UnivariateRealFunction.java"?
> --------------------------------------------------------
>
>                 Key: MATH-674
>                 URL: https://issues.apache.org/jira/browse/MATH-674
>             Project: Commons Math
>          Issue Type: Improvement
>            Reporter: Gilles
>            Priority: Trivial
>              Labels: documentation
>             Fix For: 3.0
>
>
> I noticed that because they inherit the Javadoc for "UnivariateRealFunction", all functions in package "o.a.c.m.analysis.function" have their "value" method contain a fairly large amount of documentation that is related to a marginal issue (advice about why and when a user would need to implement his own exceptions for his own functions) _that does not apply to the function being documented_.
> It might be confusing to have that documentation appear there (i.e. in a place where none of the functions are defined by the user). It should probably be moved elsewhere (user guide).

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira