Commons Lang
  1. Commons Lang
  2. LANG-337

Utility class constructor javadocs should acknowledge that they may sometimes be used, e.g. with Velocity.

    Details

    • Type: Wish Wish
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Won't Fix
    • Affects Version/s: 2.3
    • Fix Version/s: 2.4
    • Component/s: None
    • Labels:
      None

      Description

      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.)

        Activity

          People

          • Assignee:
            Unassigned
            Reporter:
            Keith R. Bennett
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development