What should we put in generated documentation in place of a bad snippet?

[Jonathan Gibbons]

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?
>