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

stddoclet: Allow {@inheritDoc} to work with more tags

    XMLWordPrintable

Details

    • Fix Understood
    • generic
    • other

    Description

      It would be useful to use {@inheritDoc} more widely.

      Currently, the {@inheritDoc} tag can only be used
      in these specific places:
       - in the text portion of @return, @throws and @param tags
       - in method comments

      Other inheritance takes place automatically.
      If and only if a Doc object does not have any @see tags of its own,
      it inherits @see text from a class or interface from higher in the
      inheritance. There is no support for inheriting other tags such as
      @since, @deprecated, etc.

      The question arises:

      1) Shall we extend {@inheritDoc} to work in constructors?
         (Constructors do no inherit functionality)

      2) Should we allow {@inheritDoc} in be used in any of the other
         tags: @see, @deprecated, @since or @serialData?
         I can see where someone might want to inherit text
         for @see and add more references:

         @see {@inheritDoc}, java.lang.String

      3) Should we allow {@inheritDoc} to work for main descriptions
         or tags in class and interface comments?

      Is it true that methods with @serialData are private, so
      {@inheritDoc} wouldn't apply there?

      Note: The above request is about an explicit {@inheritDoc}
      tag. Bug 4646560 is a request for automatic inheritance
      to also work with @deprecated like for @return, @param,
      @throws and @see.

      Attachments

        Issue Links

          Activity

            People

              prappo Pavel Rappo
              dkramersunw Douglas Kramer (Inactive)
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

                Created:
                Updated:
                Imported:
                Indexed: