KF API Documentation proposed, small, addition

[Ahmad Samir]

On 30/08/2021 16:35, Friedrich W. H. Kossebau wrote:
> 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.
> 

I agree about "should use".

For how to use a command, one should read the Doxygen docs, which are linked in the text.

> 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?
> 

They use QDoc, IIUC; and it looks like they recommend using \c
https://doc.qt.io/qt-5/04-qdoc-commands-textmarkup.html

at least that page suggests so.

> Leaving @copydoc for a separate discussion.

There are 123 instances of @copydoc in kdelibs, with the the first appearance being [1] from back in 
2003, I am mainly trying to bring it back into use, by pointing it out in the docs.

Incidentally, I think whenever we update one of the core guide pages in the wiki, we should also 
post a link to the new addition in this ML, otherwise people who already know the guidelines 
inside-out won't read the whole thing again, so they miss the new bit (or miss disagreeing with it 
and starting a discussion).

[1] https://invent.kde.org/unmaintained/kdelibs/-/commit/cd9de18af7a5b8fc752346596d1ddde512203537

> 
> Cheers
> Friedrich
> 
> 

Regards,
-- 
Ahmad Samir