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

doclet uses <section> when <div> would be correct

XMLWordPrintable

    • Icon: Bug Bug
    • Resolution: Not an Issue
    • Icon: P3 P3
    • tbd
    • 15
    • tools

      In the generated files for the declaration of a class (or package or module?) the "description" of the declaration is enclosed in a <section > as seen in this toy example:

      <section class="description">
      <dl>
      <dt>Direct Known Subclasses:</dt>
      <dd><code><a href="C.html" title="class in &lt;Unnamed&gt;">C</a></code></dd>
      </dl>
      <hr>
      <pre>abstract abstract class <span class="typeNameLabel">B</span>
      extends java.lang.Object</pre>
      </section>

      However, the HTML5 spec suggests that <section>s should normally have a heading within them:
      https://www.w3.org/TR/html52/single-page.html#elementdef-section

      The section element represents a generic section of a document or application. A section, in this context, is a thematic grouping of content. Each section should be identified, typically by including a heading (h1-h6 element) as a child of the section element.

      While it is useful to group the content of a description, in this case, it would be more appropriate to use <div> instead of <section> because the content does not include a heading.

      An alternative solution would be to put a heading in that section, but that would be a bigger change, including a arguably-gratuitous change to the visual content of each page.

            hannesw Hannes Wallnoefer
            jjg Jonathan Gibbons
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated:
              Resolved: