Hi,

by going through the code I found some suspicious code snippets:

• The method isReturnValueDocumented is unused and should be removed
• The method getDocumentedMembers returns 0, and should instead return the number of documented members (extract from getDocumentedMembersPercent)
• there is a TODO for the @return annotation regarding void methods and constructors, this can easily be integrated, see the sample code below:

    @Override
    public long getDocumentedMembers() {
        int countReturnPartial = 0;
        if (!isVoidMethod() && !doc.isConstructor()) {
            if (Arrays.stream(doc.tags()).filter(t -> t.name().equals("@return")).map(Tag::text).anyMatch(Utils::isNotStringEmpty)) {
                countReturnPartial = 1;
            }
        }
        return Utils.boolToInt(hasDocumentation()) + paramsStats.getDocumentedMembers() + thrownExceptions.getDocumentedMembers()
                + countReturnPartial;
    }

    @Override
    public double getDocumentedMembersPercent() {
        int countReturnTotal = 1;
        if (isVoidMethod() || doc.isConstructor()) {
            countReturnTotal = 0;
        }

        // this 1 is used to count the method as a element which may be documented or not
        return Utils.computePercentage(getDocumentedMembers(), 1 + getMembersNumber() + countReturnTotal);
    }

    private boolean isVoidMethod() {
        return doc.isMethod() && ((MethodDoc) doc).returnType() == null;
    }

Hi,
calling "site" with Java 9+ fails with the attached exception, with java 8 however works fine. Is there a workaround?

Thanks in advance

Attachment

Stacktrace.txt

See:

https://docs.atlassian.com/clover-maven-plugin/latest/check-mojo.html
http://www.jacoco.org/jacoco/trunk/doc/check-mojo.html
http://www.mojohaus.org/cobertura-maven-plugin/check-mojo.html

Tried using javadoc-coverage with gradle as per the steps in the README.
Get the following error : javadoc: error - invalid flag: -d

Note: Running javdaoc without the coverage doclet works fine.

Is this a known issue? Couldn't find much support elsewhere.

When having additional tags (e.g. @throws IllegalArgumentException or IllegalStateException without declaring the exception, which is not necessary as it is a runtime exception, we just want to tell the user under which circumstances this can occur) the computed percentage is wrong.

Example class where wrong numbers occur (150% for the constructor):

public class TestJavadocCoverage {

    /**
     * @param param
     *            unimportant
     * @throws IllegalStateException
     *             unimportant
     */
    public TestJavadocCoverage(int param) {
       // not important
    }
}

we used version 1.1.0 from maven central

Not sure if I missed it, but I couldnt find it in the readme nor in the code. We have several internal packages where javadoc is not required. But our public API does require it. Could you add an option to exclude classes based on a regex?

I have a rather large codebase and want to make assumptions about the javadoc-coverage only from the public (and therefore accessible from everywhere) part of the code. It would be ok for me to send you a merge request for that, but at first I wanted to know if you like the idea of having this option, too?

Apply the Visitor Pattern to enable creating classes to export documentation coverage report in different formats such as HTML, XML, JSON, YAML, etc.

The plugin configuration should use maven dependency injection to instantiate a visitor to generate the report in a specific format.

Sometimes, developers write useless javadocs such as the example below

/**
 * Some Foo Method.
 * @param id the id
 * @return 
*/
int someFooMethod(int id){ return 0; }

The plugin should spot this kind of "documentation" and present them into the report.
A common pattern to detect such useless javadocs are:

• the method documentation includes only the name of the method, accordingly separating words by space
• param documentation just includes the name or type of the param, preceded by an article (the, a, an): the id, an id, an int
• method or param documentation includes just one word.
• after removing connectors (the, a, and, of, to, for, etc) and spaces from the documentation, the text remaining is equal to the element name, for instance:

/**
 * Compute the statistics.
*/
double computeStatistics(){ return 0; }

However, it may be difficult to detect verbs in the 3rd person of the singular, such as "Computes" instead of "Compute".

Regular expressions should be defined to detect such issues. A set of regex should be defined by default, but the plugin should enable developers to specify their own regex and if they want to use both the given regular expressions and the standard ones, or just the given ones.

Reports are created from the plugins added under the reporting tag in the pom.xml .

I found out that I can't add it under the reporting tag in pom.xml because it contains the execution tag. I have to put it under the build tag and because of that it does not get added to the list of project reports for a project.

The project reports are generated by the plugins placed under the reporting tag but I can't put this plugin there.

For interface methods it is clear that they should be documented in the interface itself and not in the implementing classes (no duplicate documentation necessary!)

For methods overridden from super classes this might as well be the case, however behavior could be different in them, so there is potentially the need for additional documentation.

In general, I would ignore the second case, and count them separately, but all interface methods shouldn't be counted in the implementing classes.