KF API Documentation proposed, small, addition

[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.
> 
> Cheers
> Friedrich
> 
> 

So one vote for and one vote against, we need a tie-breaker.

Regards,
Ahmad Samir


-- 
Ahmad Samir