Javadoc @since enforcement support?

[lhazlewood]

It is important in many projects, especially libraries, to indicate which version API concepts (classes, interfaces, methods, fields, etc) were introduced. I've scoured over the current checkstyle version and looked into a bunch of GitHub issues, and I can't seem to find existing support for general JavaDoc @since annotation enforcement.

I would like to be able to enforce that:

1. A JavaDoc @since annotation is guaranteed for all public and protected classes, fields and interfaces (or any scope that I might customize really)
2. When present, has an actual value that conforms to a pattern (e.g. regex)

This support exists already for @version JavaDoc annotations, but this historically has indicated the revision control version or project version associated with the file, and is no longer really relevant for most projects given that most people these days use git/git blame to track when version control changes occurred.

What matters more IMO, and is also what Oracle does in the JDK public API, is to indicate what API version a particular feature was introduced using the JavaDoc @since annotation.

So if possible, I'd like to see the same support in checkstyle that already exists for @version to exist for @since.

Specifically, checkstyle 10.16 seems to already support this in its JavadocType module's versionFormat property: https://checkstyle.sourceforge.io/checks/javadoc/javadoctype.html#JavadocType, but there is no similar sinceFormat property.

Similar enforcement checks should also be possible, but optionally, for public or protected methods and fields. This allows specifying a different @since version for later additions (for example, adding a method in version 1.4, even though the containing class or interface was created in 1.2).

I did find #13421, but it doesn't seem like this addresses what I've described above, but it's not exactly clear to me.

Am I missing anything? Is there a checkstyle feature or behavior that already provides this support that I haven't found yet?

If not, I'd like to create a feature request issue, but wanted to discuss here first before doing so just in case.

Here's an example that would pass validation at the type level:

/**
 * This interface represents blahblahblah...
 *
 * @since 1.2
 */
public interface Something {

    /**
     * This is an awesome feature.
     */
    void whatever();
    // ... etc ...
}

And 3 different failures at the type level:

/**
 * No @since annotation, so this fails.
 */
public interface Something { // ...
}

/**
 * This fails because there is no @since value.
 * 
 * @since
 */
public interface Something { // ...
}

/**
 * This fails because the @since value does not match a version regex (e.g. num.num.num).
 * 
 * @since this_isnt_a_version
 */
public interface Something { // ...
}

At the method or field level, a missing @since annotation isn't a failure because that is assumed to mean the @since version as the enclosing class or interface. But if a field or method has @since without a value, or a value that doesn't pass regex, that is a validation failure.

Also, for what it's worth, this does not catch an empty @since:

<module name="Checker">
    <module name="TreeWalker">
        <module name="NonEmptyAtclauseDescription"/>
<!--     <property name="javadocTokens" value="SINCE_LITERAL"/>-->
<!-- </module>-->
     </module>
 </module>

That is, the following succeeds/passes validation (unexpectedly):

/**
 * An RSA Private Key using Chinese Remainder Theorem (CRT) values as defined by
 * <a href="https://datatracker.ietf.org/doc/html/rfc8017#section-3.2">RFC 8017, Section 3.2</a>'s second
 * representation.
 *
 * @since
 */
public interface CrtRsaPrivateKey extends RsaPrivateKey {
    // ... etc ...
}

Thanks!

[nrmancuso]

Hi @lhazlewood thanks for the well written discussion! I think I understand your request, but it would be very helpful if you shared code examples (roughly following our bug report template) with both “good” and “bad” Javadocs to make sure we are 100% on the same page.

[romani]

Please move all such examples in main post of discussion

[romani]

Try https://checkstyle.org/checks/javadoc/writetag.html#Example2-config , unfortunately this Check is super weird in design, but until we have have better alternative we can use it.

[lhazlewood]

Thanks @romani. Does that mean this discussion warrants converting it to an issue, to make this the better alternative?

[romani]

I don't see that we have issue on Check to demand certain tag in javadoc or improve WriteTag
https://github.com/checkstyle/checkstyle/issues?q=is%3Aissue+is%3Aopen+WriteTag

I think we can have issue on your proposal, and you can use WriteTag meanwhile.

It would be awesome if you share config that works for you, to let others to reuse your achievements.

[lhazlewood]

At least one issue is that this does not work for @since:

<module name="Checker">
    <module name="TreeWalker">
        <module name="NonEmptyAtclauseDescription"/>
     </module>
 </module>

@since is an Atclause (as that module names it), but I can have an @since without a description and that does not fail the check. Seems fairly clearly that's a bug IMO since it works for other 'Atclause's, but not a @since 'Atclause'.

This is independent of whether or not @since is required, which WriteTag does satisfy, however, as you say, it's "super weird".

And since you said "until we have a better alternative", shouldn't a new issue represent the work for the better alternative?

That is, shouldn't a sinceFormat property be allowed for JavaType and other modules?

Or, perhaps another way of asking:

When a @since annotation exists, how do I enforce that its value conforms to a specific format?

[romani]

https://checkstyle.org/checks/javadoc/nonemptyatclausedescription.html#NonEmptyAtclauseDescription works only if you have tag and just missing description, what usually lazy people happening to do.

Please share feedback on WriteTag to first unblock you, and later on we will think on better design (new Check).

[lhazlewood]

https://checkstyle.org/checks/javadoc/nonemptyatclausedescription.html#NonEmptyAtclauseDescription works only if you have tag and just missing description, what usually lazy people happening to do.

Per my reply above, this does not work for @since tags because SINCE_LITERAL is not in the subset of java tokens.

From my first post:

<module name="Checker">
    <module name="TreeWalker">
        <module name="NonEmptyAtclauseDescription"/>
<!--     <property name="javadocTokens" value="SINCE_LITERAL"/>-->
<!-- </module>-->
     </module>
 </module>

That is, the following succeeds/passes validation (unexpectedly):

/**
 * An RSA Private Key using Chinese Remainder Theorem (CRT) values as defined by
 * <a href="https://datatracker.ietf.org/doc/html/rfc8017#section-3.2">RFC 8017, Section 3.2</a>'s second
 * representation.
 *
 * @since
 */
public interface CrtRsaPrivateKey extends RsaPrivateKey {
    // ... etc ...
}

This is a bug (or missing feature if that's how it should be classified), and the "@since should adhere to a specific format" would be a feature enhancement. I'm assuming both could be addressed as a new ticket/issue.

Thoughts?