google / google/error-prone

Missing standard Javadoc tags

Open
#3,913 2 comments 1 reaction 0 assignees View on GitHub
Dominant language
Java
Stars
7.2k
Forks
820
Avg merge
5h 9m
Merged PRs (30d)
50

Description

The `InvalidBlockTag` check depends on `JavadocTag`, yet that is missing some of the tags described in [the Documentation Comment Specification](https://docs.oracle.com/en/java/javase/17/docs/specs/javadoc/doc-comment-spec.html). In my case, specifically `@hidden` (which I'm using to exclude classes from being documented that only need to be visible because of how they're used in annotations and not because they're part of any API), but it would be a good idea to synch the list of supported block and inline tags with the official list.

---

Sample warning from a recent build of mine:
```
Warning: /{long-path-elided...}/validation/UDPPort.java:[81,12] [InvalidBlockTag] The tag @hidden is not allowed on this type of element.
(see https://errorprone.info/bugpattern/InvalidBlockTag)
```
Doc comment (on static inner class, but that appears unrelated) that triggered the warning:
```java
/**
* Validator for {@link UDPPort}. Only used in Hibernate Validator.
* @hidden
*/
public static class PortValidator { /*...etc...*/ }
```
Official documentation says:
>@hidden
>--
> * `@hidden`
>
>Hides a program element from the generated API documentation. This tag may be used when it is not otherwise possible to design the API in a way that such items do not appear at all.
>
>Introduced in JDK 9.

Official `javadoc` does not complain about this tag. I do not use custom tags.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.