User:Nmariusp/KDE Docstrings

You can add e.g. comments in the C++ source code near the definition or implementation of a C++ method to document the signature of that method. These comments are docstrings. See https://en.wikipedia.org/wiki/Docstring

docstrings might contain information about why the C++ method was implemented like this, constraints on the design, bits of history, how to use the method, examples of usage, short tests, see also etc.

The KDE source code uses two technologies for docstrings: the first is kapidox + doxygen + doxyqml and the second is qdoc.

Related KDE web pages

https://community.kde.org/Get_Involved/documentation

https://community.kde.org/Guidelines_and_HOWTOs/API_Documentation

https://community.kde.org/Frameworks/Frameworks_Documentation_Policy

"kapidox generates https://api.kde.org tutorial - nmariusp" https://www.youtube.com/watch?v=CM0TWyBfCcw

"Doxygen complete tutorial - nmariusp" https://www.youtube.com/watch?v=ofrhDZl_SCk

Syntax

C++ source code comments should use a syntax that is compatible with both qdoc and doxygen. https://en.wikipedia.org/wiki/Doxygen#Design says: "In addition to the Javadoc syntax, Doxygen supports the documentation tags used in the Qt toolkit".

Maybe we should use the qdoc syntax. Because doxygen already supports the qdoc syntax.

Merge requests which add support for qdoc to KDE git repositories (e.g. https://invent.kde.org/frameworks/kcrash/-/merge_requests/67 ) do the following changes:

* Replace javadoc style "/**" with qdoc style "/*!".
* Replace javadoc style "@command" (e.g. "@note") with qdoc style "\command" (e.g. "\note").
* "@param" -> "\a"
* "@li" -> "\list
\li
\endlist"

The IDE Qt Creator has support for creating javadoc. Before an identifier, write /** then press the Enter keyboard key. Example of javadoc generated by Qt Creator:

/**
 * @brief main
 * @param argc
 * @param argv
 * @return 
 */
int main(int argc, char *argv[])

Qt Creator has support for creating qdoc. Before an identifier, write /*! then press the Enter keyboard key. Example of qdoc generated by Qt Creator:

/*!
 * \brief main
 * \param argc
 * \param argv
 * \return 
 */
int main(int argc, char *argv[])

Qt Creator creates incorrect qdoc "\param" instead of "\a". "\return" is also invalid qdoc. See https://doc.qt.io/qt-6/04-qdoc-commands-textmarkup.html

Examples

doxygen full flow

doxygen -g
# Configuration file 'Doxyfile' created.
doxygen
# Subdirectories /html, /latex are created.
# Open in a web browser the file "/html/index.html".

pdflatex
# Command 'pdflatex' not found, but can be installed with:
# sudo apt install texlive-latex-base

sudo apt install texlive-latex-base

cd /latex
make
# ! LaTeX Error: File `float.sty' not found.
sudo apt install texlive-latex-extra
make
# Open the file /latex/refman.pdf

qdoc full flow

# Save https://doc.qt.io/qt-6/21-1-minimum-qdocconf.html to /config.qdocconf
~/Qt/6.8.1/gcc_64/bin/qdoc config.qdocconf
# Directory "/public" was created.