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
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.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
