Javadoc @since enforcement support? #14848
Unanswered
lhazlewood
asked this question in
Q&A
Replies: 2 comments 6 replies
-
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. |
Beta Was this translation helpful? Give feedback.
1 reply
-
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. |
Beta Was this translation helpful? Give feedback.
5 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
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:
@since
annotation is guaranteed for all public and protected classes, fields and interfaces (or any scope that I might customize really)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'sversionFormat
property: https://checkstyle.sourceforge.io/checks/javadoc/javadoctype.html#JavadocType, but there is no similarsinceFormat
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 version1.4
, even though the containing class or interface was created in1.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:
And 3 different failures at the type level:
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
:That is, the following succeeds/passes validation (unexpectedly):
Thanks!
Beta Was this translation helpful? Give feedback.
All reactions