New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SummaryJavadoc: doesn't completely ignore inheritDoc tag #4744

Closed
rnveach opened this Issue Jul 17, 2017 · 4 comments

Comments

Projects
None yet
5 participants
@rnveach
Member

rnveach commented Jul 17, 2017

Originally fixed in #3908,

$ cat TestClass.java
/** Test. */
public class Test extends BaseClass {
 /**
 * {@inheritDoc}
 * 
 * @see #method2(String, String)
 */
    public void method() {
    }

/**
 * {@inheritDoc}. Test 2.
 */
    public void methodA() {
    }

    public void method2(String s1, String s2) {
    }
}

$ cat BaseClass.java
public abstract class BaseClass {
	/** This is my method. */
	abstract void method();

	/** This is my other method. */
	abstract void methodA();
}

$ cat TestConfig.xml
<!DOCTYPE module PUBLIC
          "-//Puppy Crawl//DTD Check Configuration 1.3//EN"
          "http://www.puppycrawl.com/dtds/configuration_1_3.dtd">
<module name="Checker">
    <module name="TreeWalker">
        <module name="SummaryJavadoc">
        </module>
    </module>
</module>

$ java -jar checkstyle-8.0-all.jar -c TestConfig.xml TestClass.java
Starting audit...
[ERROR] TestClass.java:3: First sentence of Javadoc is incomplete (period is missing) or not present. [SummaryJavadoc]
Audit done.
Checkstyle ends with 1 errors.

I am expecting no errors as inheritDoc is not a sentence and shouldn't require a period if it is completely alone in the description. The fix for #3908 still works, but it only works if inheritDoc is completely alone.

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani Jul 17, 2017

Member

@rnveach , is it valid to have some other content after {@inheritDoc} ?
how javadoc tool render this to html ?

Member

romani commented Jul 17, 2017

@rnveach , is it valid to have some other content after {@inheritDoc} ?
how javadoc tool render this to html ?

@rnveach

This comment has been minimized.

Show comment
Hide comment
@rnveach

rnveach Jul 18, 2017

Member

@romani I updated my example to reflect what I used in the javadoc tool.

is it valid

It is to javadoc tool.

javadoc1
javadoc2

Member

rnveach commented Jul 18, 2017

@romani I updated my example to reflect what I used in the javadoc tool.

is it valid

It is to javadoc tool.

javadoc1
javadoc2

@dmitry-timofeev

This comment has been minimized.

Show comment
Hide comment
@dmitry-timofeev

dmitry-timofeev Jul 19, 2017

is it valid to have some other content after {@inheritdoc} ?

It's perfectly valid, e.g., if you write a general description in a JavaDoc of a base method, and make it more specific in an overriding method (e.g., as in #4766 example, a base class documents that a method throws IllegalArgumenException if "some property of the key or the value prevents it from being stored in this map", and the overriding method specifies which these properties are).

dmitry-timofeev commented Jul 19, 2017

is it valid to have some other content after {@inheritdoc} ?

It's perfectly valid, e.g., if you write a general description in a JavaDoc of a base method, and make it more specific in an overriding method (e.g., as in #4766 example, a base class documents that a method throws IllegalArgumenException if "some property of the key or the value prevents it from being stored in this map", and the overriding method specifies which these properties are).

@romani

This comment has been minimized.

Show comment
Hide comment
@romani

romani Aug 5, 2017

Member

Fix is merged

Member

romani commented Aug 5, 2017

Fix is merged

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment