Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-6386502

allow more flexible inclusion and cross referencing of doc comments

    XMLWordPrintable

Details

    • Enhancement
    • Resolution: Unresolved
    • P4
    • None
    • 5.0
    • tools

    Description

      The new @inheritDoc javadoc tag is very useful, but a slightly more
      general facility would greatly enhance its usefulness.

      The main issue with the tag is that it inherits the entire comment
      from the class or interface which is being overridden or implemented.
      Sometimes the origin of the doc comment needs to include a sentence
      or two describing the role of the method in the overall design in
      general terms. Such a comment may be out of place or redundant in
      the documentation of the importing class as a more specific role or
      behavior may be documented more specifically there. An example
      could be:

      public interface Displayable {
          /**
           * Display the contents on the output by either
           * rendering it directly or by providing a path
           * to an image containing the contents to be
           * rendered.
           * <p>
           * All state must be made consistent with the
           * current display parameters using the validate()
           * method before the current state is displayed.
           * <p>
           * This method must not invoke any of the
           * asynchronous display methods which may generate
           * an exception.
           * <p>
           * This method may only be called while the
           * target is visible on the screen.
           * Behavior when it is called under other
           * circumstances is undefined.
           */
          public void display();
      }

      Now imagine a class implementing this method. It might start out
      by saying "Display the contents by rendering it directly" since
      this particular implementor knows that it will always choose that
      option. If it then uses @inheritDoc to include all of the details
      from the interface it will end up importing some text which mentions
      the potential choice of how the contents should be displayed, which
      will confuse developers since the doc comments now contain contradictory
      text - will it use direct rendering as it first said, or will it use
      either as it said later?

      It would be much nicer if doc comments could define an "inheritable
      section" which was written so as to be neutral with respect to choices
      made by subclasses. For example, {@beginInherit} and {@endInherit}
      could bracket the section that should be copied when an implementor
      uses {@inheritDoc}.

      An even more flexible utility would allow arbitrary blocking of
      doc sections which could be flexibly included cafeteria-style.
      Tags such as {@beginSection <name>}, {@endSection <name>} could
      delineate multiple sections which can be referred to or included in
      other doc comments using @see <name>, {@link <name>} or {@includeDoc <name>}
      tags. One could envision that each of the paragraphs in the example
      could be separately named and the implementing method could choose
      to include the sections by name (eg. validConstraint, AsyncConstraint,
      VisibilityRequirement} depending on which may apply or which may
      represent choices made by this particular implementation.

      The linking aspects of the last facility can currently be achieved by
      inlining HTML, but that practice is both awkward in the context of
      javadoc comments, and is potentially less flexible for providing
      better support for these referent sections in the javadoc output.
      One could imagine including them in an "index" (optionally if the
      tag asks for it, or doesn't request exclusion), double checking to
      make sure that the links and references both exist, etc.

      Attachments

        Issue Links

          Activity

            People

              prappo Pavel Rappo
              flar Jim Graham
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

                Created:
                Updated:
                Imported:
                Indexed: