Paul WickingandTopi Reinio
575e9c7fad
This patch introduces a new block command, `\compareswith` and
`\endcompareswith`, to QDoc.
The `\compareswith` command takes two arguments: a comparison category
and a space-delimited list of types for which the comparison category
applies. The comparison category argument must be one of the following:
`strong`
`weak`
`partial`
`equality`
The comparison category statement is generated as part of class
documentation, immediately preceding the admonition about thread
safety, and outputs e.g:
`This class is equality-comparable with Foo, Bar, and Baz.`
Any text that follows the `\compareswith` command prior to the closing
`\endcomparewith` command is generated immediately following the
comparison category statement.
This patch makes the following changes to QDoc:
- The command is added to the command hierarchy in `DocParser`,
as is code for processing the command.
- `DocPrivate` is modified to keep a map of comparison categories, a
list of types, and the detailed description.
- `Doc` is modified such that the above map can be retrieved.
- A new method is added to the `Generator` base class for generators.
The `HTMLGenerator` and `DocBookGenerator` subclasses are modified
to generate the comparison category listing for comparable types.
- Documentation of the new command is added to the QDoc manual.
- The `generatedOutput` test documentation project for the related
\compares command is extended to exercise the new command.
- Two new atom types, `ComparesLeft`, `ComparesRight`, are introduced.
- `Text` sees the addition of a new private constructor,
`Text(Atom*, Atom*)`, as well as the public method
`splitAtFirst(Atom::AtomType)`.
- The generated output test for QDoc is extended to exercise the new
block command in various ways.
In passing, ensure that DocParser::getRestOfLine() (which the
\compareswith command uses) correctly removes trailing backslashes
from a multi-line argument string.
Fixes: QTBUG-117913
Task-number: QTBUG-104110
Task-number: QTBUG-119610
Change-Id: Ie0c78443d2cc8b159594e725102eec5fab2f7598
Reviewed-by: Luca Di Sera <luca.disera@qt.io>