Repository navigation
InvalidBlockTag doesn't recognize @todo as a Javadoc tags #1811
Description
Description of the problem / feature request:
Version 2.4.0 breaks support for custom Javadoc tags.
For some of my Java projects, I'm using Maven's Javadoc Plugin to create Custom Javadoc Tags,
Mostly I use it for a @todo tag as described in the link.
Later in the project's life cycle, I use this tag to build reports and open issues.
When using Error Prone version before 2.4.0, e.g. 2.3.4, this works well.
Bumping to 2.4.0 makes the use of this tag a violation:
MyFile.java:[95,5] [InvalidBlockTag] Tag name `todo` is unknown. Did you mean tag `see`?
Feature requests: what underlying problem are you trying to solve with this feature?
I'm trying to get Error Prone to work well with custom Javadoc tags.
Bugs: what's the simplest, easiest way to reproduce this bug? Please provide a minimal example if possible.
Adding an unknown tag to a code comment should do the trick.
What version of Error Prone are you using?
With version 2.3.4 - this works well, custom Javadoc tags do not count as a violation.
With version 2.4.0 - this breaks, the custom Javadoc tag is considered a violation.
Have you found anything relevant by searching the web?
I've found this issue: 1796.
That might slightly resemble my issue.
The difference is, the other issue discusses three specific tags,
@apiNote, @implSpec, and @implNote which to my understanding are new to Java.
My issue discusses custom tags in general, although the tag in question is a @todo tag.
Activity
[-]Version `2.4.0` breaks support for custom Javadoc tags.[/-][+]Version 2.4.0 breaks support for custom Javadoc tags.[/+][-]Version 2.4.0 breaks support for custom Javadoc tags.[/-][+]InvalidBlockTag doesn't recognize @todo as a Javadoc tags[/+]cushon commentedon Jan 7, 2021
This isn't a regression in that check, it just wasn't enabled by default before 2.4.0: 6fe5156
The purpose of the check is to warn on uses of non-standard tags to avoid typos. I agree it isn't helpful when using doclets and custom tags. The best thing to do in this case might be to just disable the check, since you're deliberately using non-built-in tags?
If there was a flag to customize the list of well-known tags the check looked for, would you be interested in using that? e.g. something like
-XepOpt:InvalidBlockTag:customTags=todo?TomerFi commentedon Jan 9, 2021
Actually, I'm no using the specific custom annotation in my project anymore.
But what you're saying makes sense, I think using a flag of that sorts would be great.
mihnita commentedon Jul 31, 2022
I would love (and use) use such a flag :-)
I contribute to ICU4J and it uses custom annotations (
@draft,@final,@icu,@icuenhanced,@internal,@stable).InvalidBlockTag/InvalidInlineTag: allow specifying custom Javadoc tags
InvalidBlockTag/InvalidInlineTag: allow specifying custom Javadoc tags
cushon commentedon Feb 5, 2026
This was fixed in 1e1f293 (with help from @mihnita)