Details
-
Suggestion
-
Resolution: Unresolved
-
P2: Important
-
None
-
None
Description
QDoc currently does not support generating descriptive lists in its output (i.e., HTML <dl>, <dt>, <dd> structures), which are commonly used for term–description pairs such as command keywords and their explanations.
This limitation has been noted in documentation reviews, where descriptive lists would provide more semantic clarity and improve formatting over simple bullet lists or inline text.
Suggested Feature
Introduce support for descriptive lists in QDoc, enabling documentation authors to mark up content that naturally fits the term–description pattern. For example:
\startdesclist
\term INCLUDE
\desc Can be used to include files for import.
\term DEFINE
\desc Used to define macros and constants.
\enddesclist
Or alternatively, any other syntax that fits QDoc’s style and flexibility.
Expected Output
For HTML output, this would ideally generate:
<dl>
<dt>INCLUDE</dt>
<dd>Can be used to include files for import.</dd>
<dt>DEFINE</dt>
<dd>Used to define macros and constants.</dd>
</dl>
For other supported formats:
- DocBook: <variablelist>, <varlistentry>, <term>, <listitem>
- WebXML: I don't know if we need it; if we do, perhaps include an appropriate representation preserving the term–description semantics, potentially using <term> and <description> tags or similar XML structure.
Motivation
- Improves semantic structure and accessibility of documentation.
- Clarifies relationships between terms and their explanations.
- Aligns with common documentation standards.
- Reduces the need for ad hoc formatting or workarounds in QDoc comments.