2

I'm using Java 17 with Maven's Javadoc Plugin maven-javadoc-plugin:maven-javadoc-plugin:3.4.1 using mostly the default settings. Normally I want to be notified of missing comments (e.g. no @return), but particularly for enums this gets out of hand and isn't very useful.

Take definitions for the OpenGraph protocol as an illustration:

public enum PredefinedType {
  ACTIVITY, SPORT, BAR, COMPANY, CAFE, HOTEL, RESTAURANT, CAUSE, SPORTS_LEAGUE,
  SPORTS_TEAM, BAND, GOVERNMENT, NON_PROFIT, SCHOOL, UNIVERSITY, ACTOR, ATHLETE,
  AUTHOR, DIRECTOR, MUSICIAN, POLITICIAN, PROFILE, PUBLIC_FIGURE, CITY, COUNTRY,
  LANDMARK, STATE_PROVINCE, ALBUM, BOOK, DRINK, FOOD, GAME, MOVIE, PRODUCT, SONG,
  TV_SHOW, ARTICLE, BLOG, WEBSITE
}

Javadoc via the Maven Javadoc Plugin spits out lines and lines like this:

[WARNING] …\OpenGraph.java:…: warning: no comment
[WARNING] ACTIVITY, SPORT, BAR, COMPANY, CAFE, HOTEL …
[WARNING] ^

I am loathe to go through and add a useless comment to each of those. But I want to know if most other types of comments are missing.

How can I configure the Maven Javadoc Plugin doclint settings to ignore missing comments just for enum values? Or is there a way that I can indicate in code comments that the warning for a particular enum should be suppressed (as is possible for Checkstyle, for example)?

Garret Wilson
  • 18,219
  • 30
  • 144
  • 272
  • I don't think there is a way to do it... or that you should. As it is, you don't define the meaning of any of those terms (unless we guess based on the name). At the very least, you should provide a summary word or two, and in this case a `@see` that references the spec for each. (I'm also not convinced that an `enum` is the right way to model the concept, as that probably ought to be an open set of concepts and not a closed set. But that's a whole 'nother thing and out of scope for your question.) – Donal Fellows Nov 15 '22 at 15:58
  • "… you don't define the meaning of any of those terms …" They are defined (or should be defined) in an option specification, [OpenGraph](https://ogp.me/), which I referenced in the question. The source code Javadocs for `PredefinedType` should link to the OpenGraph specification, but I don't think it would be appropriate to try to duplicate every definition of every vocabulary item. That would cause inconsistencies and ambiguities as to which was authoritative. And OpenGraph might not even have a definition for each. So I don't think it appropriate to document each one individually here. – Garret Wilson Nov 15 '22 at 16:14
  • Anyway this is a general question, not specific to OpenGraph. It would apply to the definition of many independent specifications (HTML, CSS, RDF, SVG, MathML … I could go on all day). I don't see the benefit of going through and adding `/** See the spec. */` for each enum value. – Garret Wilson Nov 15 '22 at 16:18

0 Answers0