-
Bug
-
Resolution: Fixed
-
P3
-
13
-
b24
| Issue | Fix Version | Assignee | Priority | Status | Resolution | Resolved In Build |
|---|---|---|---|---|---|---|
| JDK-8225957 | 14 | Jonathan Gibbons | P3 | Resolved | Fixed | team |
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.
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.
- backported by
-
JDK-8225957 DocCommentParser should allow for <main> and </main>
-
- Resolved
-
- relates to
-
-
- Closed
-