User:Nmariusp/KDE Docstrings: Difference between revisions
(→Syntax) |
|||
| Line 53: | Line 53: | ||
int main(int argc, char *argv[]) | int main(int argc, char *argv[]) | ||
</pre> | </pre> | ||
Qt Creator creates incorrect qdoc "\param" instead of "\a". "\return" is also invalid qdoc. See https://doc.qt.io/qt-6/ | Qt Creator creates incorrect qdoc "\param" instead of "\a". "\return" is also invalid qdoc. See https://doc.qt.io/qt-6/27-qdoc-commands-alphabetical.html | ||
==Examples== | ==Examples== | ||
Latest revision as of 16:56, 14 December 2024
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/27-qdoc-commands-alphabetical.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. rm -rf public ; ~/Qt/6.8.1/gcc_64/bin/qdoc -debug config.qdocconf -I /home/n/Qt/6.8.1/gcc_64/include/QtCore/ -I /home/n/Qt/6.8.1/gcc_64/include # The HTML files are not generated in the directory "/public".