Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8223805

DocCommentParser should allow for <main> and </main>

    Details

    • Type: Bug
    • Status: Resolved
    • Priority: P3
    • Resolution: Fixed
    • Affects Version/s: 13
    • Fix Version/s: 13
    • Component/s: tools

      Backports

        Description

        This is about reading standalone HTML files in javadoc, generally as found in a doc-files subdirectory.

        The file is parsed into sections, the preamble, the body, the block tags, and the postamble.

        Currently, the preamble is every from the beginning up to and including '<body>', and the postamble is everything from '</body>' to the end of the file. This means that if the user provides '<main>' and '</main>' tags, they will be included in the body section and/or tags sections, which causes downstream problems because the doclet generally is currently responsible for generating '<main>'.

        It's especially bad when the user puts block tags at the end of their main content. For example, consider this:

        <html>
        <head>
        <title>my file</title>
        </head>
        <body>
        <main>
        My description.
        @since MyVersion
        </main>
        </body>
        <html>

        This will be parsed with an unbalanced `<main>` at the beginning of the main body section, and an unbalanced `</main>` as part of the @since tag, which will end up *within* the <dl> list used for block tags! (which is incorrect HTML!)

        Although a short-term workaround might be to restrict the use of <main>...</main> within HTML doc-files, that is bad for users that might be using style checkers for such files.

        A better solution may be to detect the use of <main> and include it in the preamble, and detect the use of </main> and use it to end the section being read and to begin the postamble.

          Attachments

            Issue Links

              Activity

                People

                • Assignee:
                  jjg Jonathan Gibbons
                  Reporter:
                  jjg Jonathan Gibbons
                • Votes:
                  0 Vote for this issue
                  Watchers:
                  1 Start watching this issue

                  Dates

                  • Created:
                    Updated:
                    Resolved: