commons-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Henri Yandell (JIRA)" <j...@apache.org>
Subject [jira] Closed: (LANG-337) Utility class constructor javadocs should acknowledge that they may sometimes be used, e.g. with Velocity.
Date Thu, 09 Aug 2007 00:34:59 GMT

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

Henri Yandell closed LANG-337.
------------------------------

    Resolution: Won't Fix

Apologies in the length between this being reported and getting around to looking at it closely
Keith.

Once I get to looking at every Utils class, there is a second paragraph that says:

     * <p>This constructor is public to permit tools that require a JavaBean
     * instance to operate.</p>

This seems to cover your report above, so I'm marking this as wontfix. Please reopen if you
think more is needed.

> Utility class constructor javadocs should acknowledge that they may sometimes be used,
e.g. with Velocity.
> ----------------------------------------------------------------------------------------------------------
>
>                 Key: LANG-337
>                 URL: https://issues.apache.org/jira/browse/LANG-337
>             Project: Commons Lang
>          Issue Type: Wish
>    Affects Versions: 2.3
>            Reporter: Keith R. Bennett
>            Priority: Minor
>             Fix For: 2.3.1
>
>
> Utility class constructors currently have javadoc comments that say:
> "StringUtils instances should NOT be constructed in standard programming."
> However, there are some cases where it is necessary to use them to create instances.
 For example, using the utility methods in a Velocity context requires that an instance be
created.
> It is true that the current comment does not exclude this use, but the emphasis ("NOT")
implies that there is a possibility it will be deprecated, removed, or otherwise be made inaccessible
in the future.
> I'd like to suggest modifying the message to more explicitly acknowledge that the constructor's
use is approved in some cases, so as to reassure developers that it will continue to be available
in the future.
> One possible wording would be to retain the existing comment, and add to it:
> "However, in some cases (for example, for use with Velocity), it is necessary to create
an instance of this class.  It is recommended that this constructor be used only in special
cases such as this."
> (This issue really applies to all projects with utility classes with this javadoc, so
feel free to copy it them as well.)

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.


Mime
View raw message