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
