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?
