If we can't interpret it, don't.
If the user pushes the code beyond the point where javadoc would
normally stop, I suggest we should output the contents of the
ErroneousTree "as is", perhaps with a metaphorical blinky-red border.
The same argument might (should?) go for any ErroneousTree.
-- Jon
On 9/6/21 8:25 AM, Pavel Rappo wrote:
I cannot recall any conversation on what to put in generated documentation in
place of an erroneous construct in a doc comment. The ongoing work on JEP 413
(Snippets) reminded me of that problem. Although it's by no means unique to
snippets, here I only consider snippets.
If for whatever reason a snippet cannot be output, what should be displayed
instead of it? It should go without saying that in such a case javadoc must
generate an error for the author to see and fix. But then again, authors don't
always pay attention to errors, much less warnings, coming out of javadoc
(tool). I've seen that many times. So it's only reasonable to plan for what to
do when (not if) such mistakes slip through the author' fingers.
I think we need a clear indication to the reader that this is not what they should've
seen. Currently, we display the "bad snippet" text using a regular snippet
decoration. I think we might need to do more than that. Maybe we could use a different
color (red?) theme such that it couldn't be changed from within a snippet tag.
Thoughts?
