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
