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

[Phil Race]

On Wed, 15 Jun 2022 17:27:53 GMT, Damon Nguyen <dnguyen at openjdk.org> wrote:

>> Updated Parser class doc by appending to the doc regarding lack of support for HTML script tags. Adding this information to the "parse" function did not seem as consistent for formatting as adding it to the Parser class doc.
>
> Damon Nguyen has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Moved doc change.

Changes requested by prr (Reviewer).

src/java.desktop/share/classes/javax/swing/text/html/HTMLEditorKit.java line 1184:

> 1182:      * table describes what this factory will build by
> 1183:      * default.
> 1184:      * <p>

I think it fine to add @implNote right here.

src/java.desktop/share/classes/javax/swing/text/html/HTMLEditorKit.java line 1188:

> 1186:      * When the container using HTML tags is editable, all non-supported tags
> 1187:      * will be displayed as editable text fields in place of the tags. The contents
> 1188:      * within the tags will be handled by the editor as regular text.

new paragraph - to force a new line here

and "full support" what does that mean ?

src/java.desktop/share/classes/javax/swing/text/html/HTMLEditorKit.java line 1190:

> 1188:      * within the tags will be handled by the editor as regular text.
> 1189:      * If the container is not editable and a tag is recognized but not supported,
> 1190:      * such as script tags, the tag and its contents will be hidden.

another nl here I think. This is almost like a list, but the main point is it is easier to read the conditions when there's a line break. Remember your formatting doesn't get carried over into the published javadoc

src/java.desktop/share/classes/javax/swing/text/html/HTMLEditorKit.java line 1192:

> 1190:      * such as script tags, the tag and its contents will be hidden.
> 1191:      * If the container is not editable and a tag is unknown or not supported at
> 1192:      * all, the tags will be hidden but its contents will display as regular text.

"unknown or not supported at all" ?
unknown tags are surely always unsupported so why do we need to say that here ?

With all the above it ends up something like 
     * @implNote
     * Parsed tags that are unrecognized or are recognized but unsupported are handled differently by the editor.
     * <ul>
     * <li> When the container using HTML tags is editable, all such tags
     * The contents will be displayed as editable text fields in place of the tags.
     * The content within the tags will be handled by the editor as regular text.
     * <li> If the container is not editable and a tag is recognized but not supported,
     * such as script tags, the tag and its contents will be hidden.
     * <li> If the container is not editable and a tag is unknown
     * the tag will be hidden but its contents will display as regular text.
      *</ul>
     * <p>
     * <p>

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

PR: https://git.openjdk.org/jdk/pull/7446