KF API Documentation proposed, small, addition

[Ahmad Samir]

On 09/09/2021 22:47, Friedrich W. H. Kossebau wrote:
> Am Donnerstag, 9. September 2021, 22:35:05 CEST schrieb Ahmad Samir:
>> On 09/09/2021 22:24, Friedrich W. H. Kossebau wrote:
>>> Am Donnerstag, 9. September 2021, 21:45:33 CEST schrieb 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:
>>>>> 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.
>>>
>>> Then our question was not "if" they have a command to markup things to be
>>> printed code-like, but "when" it should be used. And the examples they
>>> give
>>> (not sure though if exclusive or inclusive) are
>>>
>>> "
>>> variable names, user-defined class names, and C++ keywords (for example,
>>> int and for)
>>> ".
>>>
>>> So no mention of names of the methods, members, properties and classes the
>>> documentation is about (note the "user-defined"). And looking at the
>>> existing Qt API documentation, I would guess the given list is rather
>>> exclusive then, and \c with Qt is not to be used when referencing the
>>> elements of the documented API itself (at least in flow text).
>>>
>>> Myself I meanwhile rather think that this might be a good choice. Imagine
>>> how e.g. https://doc.qt.io/qt-6/qstring.html would look like if all text
>>> elements referencing Qt classes or method names would be in code-style. I
>>> guess the reading flow in the flow text blocks would suffer a lot.
>>>
>>
>> So one vote for and one vote against, we need a tie-breaker.
> 
> What I would like to see are some argument for why you want this change?
> What is broken now, what does it improve?
> Can you give an example where your proposal is applied and what the result is,
> before and after?
> 

I think it's useful to markup the method names, that makes reading the API docs in text format in a 
header file easier, the same way marking up true/false is useful, the same way syntax highlighting 
in most text editors is useful.

For examples, open any header file in a KDE repo and add @c before a method name in the comment 
above any method. :)

> Cheers
> Friedrich
> 
> 


Regards,
Ahmad Samir