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

[Jonathan Gibbons]

As for "red", it should be a new CSS style, with a name like `error` 
that is configured in the stylesheet to have some culturally appropriate 
rendition.

-- Jon

On 9/6/21 3:20 PM, Jonathan Gibbons wrote:
> 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?
>>