Skip to content
  • Thiago Sueto 🐰 @thiagosueto ·

    A few notes so far:

    The metatask about porting API docs to QDoc is in https://invent.kde.org/teams/goals/streamlined-application-development-experience/-/issues/10.

    When converting @param commands to \a it is recommended to add empty lines around it to force a line break in the rendered HTML.

    This applies even (or especially) between \a commands, example:

    \a title

\a message

\a icon

\a timeout

    \enum EnumName

    The above automatically does the same as using the full enum name:

    \enum Class::EnumName

    In some cases (like when two classes have the same enum name) this is necessary for QDoc to recognize the enum, otherwise the following message would appear:

    warning: Cannot find 'EnumName' specified with '\enum' in any header file

    Qt seems to use this enum style: https://doc.qt.io/qt-6/13-qdoc-commands-topics.html#enum-command

    /*!
 *  \enum Class::EnumName
 *
 *  Enum description.
 *
 *  \value EnumValue
 *         Value description.
 *  \value AnotherValue
 *         AnotherValue description.
 */

    Which works very well to separate values. To some extent we were doing this in Doxygen as well (keeping the indentation but without the newline).

    We have custom functionality regarding enums (not in QDoc I think).

    We can specify \since for enum values:

    \enum Class::EnumName

\value [since 6.5] FirstValue
       FirstValue description.

    Unfortunately it shows as:

    Class::EnumValue (since Qt 5.5.5)

    in the Constant column, saying Qt instead of the class name.

    Automatic linking might not work inside \note blocks or in .qdocconf / .qdoc files, so they need to be forced with \l.

    The order of \sa calls is significant and determines the order of "See also" links that will be shown.

    Newlines are significant, so they must be added after \brief and other cases where you want a separating newline.

    Using \overload might require using the fully qualified name for a method.

    So instead of:

    \overload KShortcutsEditor()

    Do:

    \overload KShortcutsEditor::KShortcutsEditor()

    We should use \reimp for cases where we see @reimp or "Reimplemented from", except in cases where the reason for the reimplementation matters.

    When dealing with \qmlmethod, use the fully qualified name (Class::method) and full parameter signature (including const and default values). Function const is ignored.

    For example, for a function like:

    class KCMLauncher {
...
void openSystemSettings(const QString &name, const QStringList &args = QStringList()) const;
}

    Either of these works:

    \qmlmethod KCMLauncher::openSystemSettings(const QString &name, const QStringList &args = QStringList())
or
\qmlmethod KCMLauncher::openSystemSettings(const QString &name, const QStringList &args = QStringList()) const
    Edited by Thiago Sueto
  • Thiago Sueto 🐰 @thiagosueto ·

    Useful sed to automate most of the changes:

    sed -i -e 's/\/\*\*/\/*!/g' -e 's/@class/\\\class/g' -e 's/@brief/\\\brief/g' -e 's/@short/\\\brief/g' -e 's/@see/\\\sa/g' -e 's/@code/\\\code/g' -e 's/@endcode/\\\endcode/g' -e 's/@returns/Returns/g' -e 's/@return/Returns/g' -e 's/@note/\\\note/g' -e 's/Note:/\\\note/g' -e 's/NOTE:/\\\note/g' -e 's/@warning/\\\warning/' -e 's/@since/\\\since/g' -e 's/@ref/\\\l/g' -e 's/@c/\\\c/g' -e 's/@image html/\\\image/g' -e 's/\\\image html/\\\image/g' -e 's/@internal/\\\internal/' -e 's/@reimp/\\\reimp/g' -e 's/@p /\\\a /g' -e 's/\\\p /\\\a /g' -e 's/@param/\\\a/g' -e 's/@verbatim/\\\badcode/g' -e 's/@endverbatim/\\\endcode/g' -e 's/@inherits/\\\inherits/g' -e 's/@deprecated/\\\deprecated/g' <thefileyouwant>

    In expanded form for better legibility:

    Click to open 
    sed -i \
-e 's/\/\*\*/\/*!/g' \
-e 's/@class/\\\class/g' \
-e 's/@brief/\\\brief/g' \
-e 's/@short/\\\brief/g' \
-e 's/@see/\\\sa/g' \
-e 's/@code/\\\code/g' \
-e 's/@endcode/\\\endcode/g' \
-e 's/@returns/Returns/g' \
-e 's/@return/Returns/g' \
-e 's/@note/\\\note/g' \
-e 's/Note:/\\\note/g' \
-e 's/NOTE:/\\\note/g' \
-e 's/@warning/\\\warning/' \
-e 's/@since/\\\since/g' \
-e 's/@ref/\\\l/g' \
-e 's/@c/\\\c/g' \
-e 's/@image html/\\\image/g' \
-e 's/\\\image html/\\\image/g' \
-e 's/@internal/\\\internal/' \
-e 's/@reimp/\\\reimp/g' \
-e 's/@p /\\\a /g' \
-e 's/\\\p /\\\a /g' \
-e 's/@param/\\\a/g' \
-e 's/@verbatim/\\\badcode/g' \
-e 's/@endverbatim/\\\endcode/g' \
-e 's/@inherits/\\\inherits/g' \
-e 's/@deprecated/\\\deprecated/g' \
<thefileyouwant>

    Explanation:

    • -i = in place modification, keep a backup file by using -ibak or use git restore to revert
    • 's/\/\*\*/\/*!/' = /** -> /*!
    • \\\ is necessary to actually result in a single \, otherwise you get ^L
    • sed runs step by step, so the @returns substitution needs to come before @return

    After that, you can then open the file and perform the required manual modifications.

    Absolutely required:

    • Fix enums manually in C++
    • Remove * in QML
    • Add \inqmlmodule and \inherits in QML
    • Add \qmlproperty for aliases in QML
    • Check for missing images (specify imagedirs = ../path/to/images in the qdocconf)
    • Check for broken brief class description (usually caused by missing * used together with @verbatim)
    • Check for missing spaces before and after \a
    • Check for any /// that need to be transformed into /*! ... */
    • Check for documentation (inside /*!) that is actually supposed to be a comment instead of API docs (should be /*)
    • Check for \sa which is sometimes erroneously used inline
    • Check that each Q_PROPERTY has at least a \property in it (requires the Class::property part, but not a description)
    • Use \fn to make templates show up

    Not absolutely required, but will have to be done eventually:

    • Add \inmodule after \class
    • Remove lingering arguments in \class
    • Remove @author and add SPDX on top if necessary
    • Check \code for whether it should be \qml or \badcode
    • Check for the string "Return" or "Returns" manually for caps or inline Return text
    • Add \brief where necessary (it's needed for class descriptions to show up in the module page)
    • Add missing brief descriptions
    • Substitute any lingering HTML entities (Doxygen had certain limitations when displaying characters so occasionally HTML entities were used to compensate for this)
    • Change "Defaults:" to \default in QML
    Edited by Thiago Sueto
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please to comment