#457 Interpretation of {@inheritDoc} is flawed

release_4.2
open
nobody
5
2014-02-09
2006-12-11
DGardner
No

There are problems with the way Checkstyle handles
the {@inheritDoc} Javadoc tag. These seem to stem
from a misunderstanding of the meaning and purpose
of that tag.

The Javadoc tool is documented here:

http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html

The Javadoc tool has a mechanism for the "Automatic
Copying of Method Comments" where the main description
or tag descriptions are missing. Any missing parts of
the method Javadoc will be copied automatically from
a relevant interface or super-class. This does not
depend on the {@inheritDoc} tag. This behaviour was
introduced in Java 1.4; before that, the automatic
copying would only be performed if the method comment
was completely empty.

The {@inheritDoc} tag can be used in the main
description block of a method comment and in the
descriptions of the @return, @param and @throws
tags. The tag is an explicit instruction to copy the
corresponding main description or tag description
from an interface or super-class to that position
in the method comment. For example, the simple
comment:

/*
* {@inheritDoc}

/

is an instruction to copy the main description text
of some relevant interface or super-class into this
position in the main description text of this comment.
If the {@inheritDoc} tag were not there, this would be
done automatically anyway, so it is quite redundant
when used like this. This tag is NOT an instruction to
copy in the descriptions of any other tags (@param,
@return, or @throws); however, that copying will be
done automatically if those tags are missing.

If you omit main description or tag description, it
will be copied automatically; if you write your
own, it will be used instead. The purpose of the
new {@inheritDoc} tag is to allow you to combine
descriptions. For example, this simple interface
defines a method with a Javadoc comment:

public interface A {
/
* Sets the value.


* @param value The new value.

/
void setValue(int value);
}

The following class implements the interface, but the
implementation does nothing, so the developer would
like to combine the Javadoc on the interface with
information about this implementation detail. It can
be done the old way by hand-copying the interface's
Javadoc text:

public class B1 implements A {
/
* Sets the value. This implementation of the
* interface method really does nothing at all.


* @param value The new value. Not used.

/
public void setValue(int value) {
// Do nothing.
}
}

or it can be done the new way (since Java 1.4) by
using {@inheritDoc} to copy in the text from the
interface and to add additional text:

public class B2 implements A {
/
* {@inheritDoc} This implementation of the
* interface method really does nothing at all.


* @param value {@inheritDoc} Not used.

/
public void setValue(int value) {
// Do nothing.
}
}

From this information, is it clear that it is NOT
true that the {@inheritDoc} tag, as described in bug
1290379, "results in copying the entire parent
definition javadoc", or that if the comment just
contains a single {@inheritDoc} tag, as described in
bug 855839, that you "don't have to repeat the @param
and @return tags for that method". Both of these bugs
are based on an assumption that the

Unless you actually want to augument the text of the
main description text or the text of a Javadoc tag,
the {@inheritDoc} tag is redundant.

Now form some problems. Checkstyle will allow this:

public class C implements A {
/*
* {@inheritDoc}

/
public void setValue(int value) {
// Do nothing.
}
}

but will not allow this:

public class D implements A {
/*
* Does nothing.

/
public void setValue(int value) {
// Do nothing.
}
}

Checkstyle accepts the method comment in class "C"
yet for class "D" it complains that the "value"
parameter is missing an @param tag. In fact, BOTH
method comments are missing the @param tag and BOTH
method comments are depending on the same rules for
the automatic copying of method comments to be applied
to copy in the parameter description from the
comment on the interface's method. The presence of
{@inheritDoc} in one comment and not the other has
no affect on this at all. There is no guarantee that
there will even be any main description text or
@param description text to be inherited.

As it stands, Checkstyle allows me to rely on the
automatic copying of the description text of tags,
but ONLY if I agree to copy the main description
text explicitly. If I want to write alternative main
description text, I am no longer allowed to rely on
the same mechanism for copying the tag descriptions.

I'm not sure how Checkstyle works when checking
Javadoc: Does it know if there is any text available
to be inherited? I'm guessing that it doesn't, so,
for practical reasons, there may need to be a simple
way to tell it that the content is not missing and
that the developer is explicitly relying on it being
copied from an interface or super-class. In this
respect, the distinction between:

/*
* {@inheritDoc}

/

and an empty or missing comment is probably useful.

However, such semantics should not be at odds with
the meaning and purpose of {@inheritDoc}. If the
only purpose it really serves is to indicate that
the developer is aware that copying of other tag
descriptions will occur automatically, then any
other mechanism that indicates the same thing should
do just as well. There is no reason why a lone @see
tag should not be acceptable too: if we are willing
to rely on the automatic copying of the description
text of all of the tags, why not rely on the copying
of the main description text too. The presence of
the @see tag suggests that the developer is aware
that the comment is incomplete and that there is a
reliance on the automatic copying mechanism. That
indication is not much different from the presence
of the lone {@inheritDoc} tag.

In fact, the @see tag is somewhat safer and more
flexible in situations where there are no
descriptions to inherit. Using {@inheritDoc} with
nothing to inherit results in no Javadoc and no
warnings from the Javadoc tool. This is exactly what
Checkstyle is trying to prevent. Using @see will
at least result in a link, and that may be a link
to a similar method with proper Javadoc, as it is
not necessarily the overridden or implemented
method--other text will be copied automatically if
it is available.

The @see tag also makes sense in constructors, where
{@inheritDoc} does not have any affect and where
Checkstyle 4.2 no longer allows its use. Constructors
are not inherited, but they often have the same
parameters with the same names and the same meanings.

Resolving what to do in more confusing situations
such as in the examples above (class "C" vs. "D") is
not as clear cut. The method comment in class "D"
does not signal any obvious awareness on the part
of the developer that there is no @param tag. While
class "C" does signal some awareness that the tag
description might be inherited. However, both are
dependent on the same copying mechanism, the presence
of {@inheritDoc} in class "C" does not affect the
copying of tag descriptions any more than the comment
in class "D", and neither mechanism guarantees that
there is any tag description to inherit at all anyway.

I request that Checkstyle be changed so that the
Javadoc be considered valid if it contains a single
@see tag. This will result in the much the same
Javadoc being generated as the use of a redundant
{@inheritDoc} tag. The single @see tag signals the
same intent: that the documentation is available
elsewhere--it will be inherited or it is similar
to other documentation. The additional link adds
flexibility in cases where there is nothing to
inherit, something that {@inheritDoc} does not
provide. The current check permitting the redundant
{@inheritDoc} tag should also be preserved, as it
does not do much harm.

A refinement might permit incomplete Javadoc content
in the presence of an @see tag if the @see tag links
to a method with the same name and signature (i.e.,
any missing content will probably be inherited
automatically).

Discussion

  • Jason Bennett
    Jason Bennett
    2007-03-31

    Logged In: YES
    user_id=61134
    Originator: NO

    Another approach would be to look for @Override on a method, and not throw a Javadoc warning if one is found. If the parent method is also not doc'ed, it will throw its own warning.

     
  • DGardner
    DGardner
    2007-04-02

    Logged In: YES
    user_id=1663951
    Originator: YES

    There are problems with the @Override suggestion: @Override is only
    used when overriding a concrete method of a superclass, it is not
    used when implementing an abstract method or a method of an interface;
    neither does @Override imply that the source code (and hence the
    Javadoc) of the superclass is available to be inherited. For example,
    if I implement the "java.util.List" interface, I cannot use @Override
    (because it is an interface) and I cannot inherit the Javadoc (because
    I'm compiling against the JRE bytecode).

    Not having access to the inherited Javadoc is not specifically a problem
    for @Override, though. I think that is something that Checkstyle cannot
    solve easily and it may be unreasonable to expect it to do so.

     
  • Oliver Burn
    Oliver Burn
    2007-04-09

    Logged In: YES
    user_id=218824
    Originator: NO

    Wow - thanks for such a detailed request. To answer your question, Checkstyle does not have access to information about whether a method can inherit/copy Javadoc comments from a parent. This is because Checkstyle does not parse the Java code for type information to enable this type of checking. This is a conscious design decision.

    I use Checkstyle on the project I have been working on for the last two years. It has a zero tolerance to Checkstyle errors, which is impressive (IMHO) when you consider that the code base has 800,000+ lines of Java code. All code must have a valid Javadoc comment, except for setters and getters. We use the {@inheritDoc} technique to signify that the Javadoc can be taken from the parent. We do not rely on the automatic copying of method comments (http://tinyurl.com/2wlnv7), as it would mean that developer do not explicitly have to provide a Javadoc comment.

    Any change in the behaviour to the JavadocMethodCheck would have a huge impact on our project, especially as we have the zero tolerance to errors. Now magnify this out for all projects that use Checkstyle. In the end I have the feeling of "damned if I, damned if I don't".

    I think ultimately it is best to introduce different strategies for checking the Javadoc based on the version of the JDK being used. My current project is based on JDK1.4 so cannot use the @Override technique. Further, the @Override technique changed in JDK 6 to allow it to be used for interfaces.

     
  • BenniL
    BenniL
    2010-09-16

    Our Problem is the same: We have more than 1000 @see-comments. It would be nice if we can configure checkstyle to allow single @see tags.
    What has become of it?

     
  • Roman Ivanov
    Roman Ivanov
    2014-02-06

    • labels: Core Framework --> Core Framework, JavaDoc
    • Description has changed:

    Diff:

    --- old
    +++ new
    @@ -1,4 +1,3 @@
    -
     There are problems with the way Checkstyle handles
     the {@inheritDoc} Javadoc tag. These seem to stem
     from a misunderstanding of the meaning and purpose