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

[Damon Nguyen]

On Tue, 31 May 2022 20:03:25 GMT, Phil Race <prr at openjdk.org> wrote:

>> Damon Nguyen has updated the pull request incrementally with three additional commits since the last revision:
>> 
>>  - Updated java doc for clarity. Added test to show behavior.
>>  - Merge branch '8012675/htmlTagParserDocChange' of github.com:DamonGuy/jdk into 8012675/htmlTagParserDocChange
>>  - Added debugging statements to better trace handleComments
>
> 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.

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

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