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

[Pavel Rappo]

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?