KF API Documentation proposed, small, addition

[Ahmad Samir]

On 09/09/2021 23:34, Friedrich W. H. Kossebau wrote:
> Am Donnerstag, 9. September 2021, 23:23:29 CEST schrieb 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.
> 
> I see, that is where you are coming from, it makes some sense there. But...
> 
> ... it only makes sense for people looking at headers in a plain text editor
> which also is capable of parsing doxygen comments and adding respective
> highlighting.
> 
> .. for every other plain text viewers/editors, including on the gitlab file
> viewer, it makes things harder to read.
> 

I don't see how it's harder to read the API docs than '@c true' or '@param'
or any other doxygen command when viewed in an editor that doesn't highlight doxygen syntax 
properly; those same editors highlight C++ code properly?

> .. it very possibly lowers the quality of the generated API docs, which should
> be the main purpose of writing those API documentation snippets, no?
> 
> So im summary not convinced this would be a change for the better.
> 
> Cheers
> Friedrich
> 
> 

Since no one else seems to care either way, I'll drop the matter.

Regards,
Ahmad Samir