When to use "code"-style for code expressions in API docs? (was: Re: KF API Documentation proposed, small, addition)

[Friedrich W. H. Kossebau]

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