Thanks for pushing this here. Am Montag, 30. August 2021, 14:17:42 CEST schrieb Ahmad Samir: > I would like to add the following to: > https://community.kde.org/Frameworks/Frameworks_Documentation_Policy#Documen > t_the_Classes > > > One can use [https://www.doxygen.nl/manual/commands.html Doxygen commands] > to improve readability, for example > * @c which will make the word after it use a monospace/typewriter font face, > typically e.g. @c true, @c false, @c setSomeValue(); for multiple words > you'll have to use: <pre><tt>multiple words</tt></pre> > * @copydoc to copy the docs of a different method, e.g. if one method > overloads another
I propose to turn "can use" into "should use" and define where which command should be used where (and which variant in case of aliases), for a consistent result. Doxygen commands are already used, so I cannot see how the current proposal for an addition makes a difference about helping when to do what? So in the given case, the motivation of the proposal is to improve the resulting documentation to have all in-text (C++) code expressions to be formatted in code-typical ways (i.e. monospace fonts). So far this was mainly done for literal code expressions like "nullptr", "true" and "false", whereas method names or class names were not, until recently at least. Open question: in which places is it a good idea to use "code"-style with class names and method names? So when does readability suffer by too many changes in the formatting in a text body? Looking e.g. at the Qt docs for a reference, they do not use "code"-style when referencing classes or methods from text, as well as in the listing of classes and methods. So I wonder if this is by design or just historic? Leaving @copydoc for a separate discussion. Cheers Friedrich
