RFR: 8012675: Javadoc for javax.swing.text.html.parser.Parser.handleComment() needs to be updated [v3]

[Damon Nguyen]

On Tue, 31 May 2022 22:53:25 GMT, Damon Nguyen <dnguyen at openjdk.org> wrote:

>> src/java.desktop/share/classes/javax/swing/text/html/parser/Parser.java line 73:
>> 
>>> 71:  * <p>
>>> 72:  * Unsupported tags, such as script tags, will be handled by HiddenTagView. The
>>> 73:  * tags and its contents will be displayed as editable JTextFields and JTextAreas.
>> 
>> HiddenTagView is a JDK internal class.
>> It doesn't appear anywhere in the specification of Java SE.
>> So, whatever it is you need to say, can't be written like this.
>> 
>> Also I am not sure that the PARSER has any say in the display does it ? It just hands it off to something else to decide what to do .. doesn't it ? So can it be correct to mention JTextField here ?
>> 
>> Furthermore, the mention of "editable" is pertinent.
>> I think (haven't verified) that if you are viewing a document then comments etc are hidden, but when editing it, they are visible, and that is when handleComment() matters.
>> 
>> 
>> Perhaps you want
>> Unsupported tags, such as script tags,  will be treated similarly to comments and so will be handled in the same way as these by the editor. For example it might be invisible when reviewing the document, and raw editable text when editing it.
>> 
>> You need to fact check my assumptions ..
>
> I see your points and agree that your points are valid. Parser has no part in the display and is fact handled elsewhere.
> 
> I initially had to look through and learn what each class for HTML parsing is responsible for, and Parser is meant to handle reading chars and adding the chars to a buffer to be processed elsewhere. In this case, I found the HTML contents were routed to DocumentParser. And from there, I had to trace the stack and add debugging statements to find that hidden tags were responsible for the specialized text fields and text areas that appeared. 
> 
> I'll definitely iterate on the documentation to increase clarity and remove mention of HiddenTagView.

The editor kit is responsible for delegating which tags will be displayed this way. The list of tags supported can be located in the HTML class, and it's worth noting that script tag is among the tags listed here. But, there is another list of tags in the editor kit's code which are the tags that do not have full support. Script tags are one of these tags; another example being title tags. These tags that are not fully supported, alongside unknown tags, are being passed into HiddenTagView and being displayed as such. So, I tried simplifying the doc description to state the behavior as relevant to the Parser class only. Maybe additional documentation is required in HTMLEditorKit as well?

-------------

PR: https://git.openjdk.java.net/jdk/pull/7446