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

Using @inheritdoc in an inapplicable context shouldn't crash javadoc

XMLWordPrintable

    • Icon: CSR CSR
    • Resolution: Approved
    • Icon: P3 P3
    • 19
    • tools
    • None
    • behavioral
    • low
    • Hide
      JDK does not use `{@inheritDoc}` on class or interface declarations anywhere except for a few tests, which will be fixed as a part of this effort. It is unlikely that `{@inheritDoc}` is noticeably used on class or interface declarations outside of JDK. This is because that ability was never advertized, supported or properly implemented. Some IDEs detect and warn against such a use.
      Show
      JDK does not use `{@inheritDoc}` on class or interface declarations anywhere except for a few tests, which will be fixed as a part of this effort. It is unlikely that `{@inheritDoc}` is noticeably used on class or interface declarations outside of JDK. This is because that ability was never advertized, supported or properly implemented. Some IDEs detect and warn against such a use.
    • File or wire format

      Summary

      Clarify applicability of {@inheritDoc} in the Documentation Comment Specification for the Standard Doclet.

      Problem

      {@inheritDoc} was introduced in JDK 1.4 to be used in the main description, @return, @throws and @param block tags of method documentation. JDK 1.8 expanded {@inheritDoc} onto custom single-argument block tags likely to cover then-developed @apiNote, @implSpec and @implNote.

      For whatever reason, along with expanding the set of applicable tags, JDK 1.8 implementation also expanded the set of applicable locations: {@inheritDoc} was allowed to appear not only in method documentation, but also in class or interface documentation. That was never properly documented or implemented.

      Solution

      Although there is an ongoing investigation on allowing some use of {@inheritDoc} outside of the method documentation (JDK-6327933), for the sake of the Standard Doclet Specification, we propose to currently limit {@inheritDoc} to work on methods and remove the confusing parts of the specification that gave an impression that {@inheritDoc} could be applied to class or interface documentation. This is not a restriction, but rather an actualization.

      Specification

      diff --git a/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md b/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md
index ce2e928fc5..d5e85902d6 100644
--- a/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md
+++ b/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md
@@ -1026,7 +1026,7 @@ Table: Contexts in which tags may be used
 | [`@exception`](#exception)            |          |         |         |         | ✓     | ✓ |         |
 | [`@hidden`](#hidden)                  |          |         |         | ✓ |             | ✓ | ✓ |
 | [`
{@index}
`](#index)                  | ✓  | ✓ | ✓ | ✓ | ✓     | ✓ | ✓ |
-| [`
{@inheritDoc}
`](#inheritdoc)        |          |         |         | ✓ |             | ✓ |         |
+| [`
{@inheritDoc}
`](#inheritdoc)        |          |         |         |         |             | ✓ |         |
 | [`
{@link}
`](#link)                    | ✓  | ✓ | ✓ | ✓ | ✓     | ✓ | ✓ |
 | [`
{@linkplain}
`](#linkplain)          | ✓  | ✓ | ✓ | ✓ | ✓     | ✓ | ✓ |
 | [`
{@literal}
`](#literal)              | ✓  | ✓ | ✓ | ✓ | ✓     | ✓ | ✓ |

            prappo Pavel Rappo
            prappo Pavel Rappo
            Jonathan Gibbons
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated:
              Resolved: