Re: KF API Documentation proposed, small, addition
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. .. 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
Re: KF API Documentation proposed, small, addition
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
Re: KF API Documentation proposed, small, addition
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? Cheers Friedrich
Re: KF API Documentation proposed, small, addition
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
Re: KF API Documentation proposed, small, addition
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
Re: KF API Documentation proposed, small, addition
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: multiple words * @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
KDE CI: Frameworks » kirigami » kf5-qt5 WindowsMSVCQt5.15 - Build # 461 - Fixed!
BUILD SUCCESS Build URL https://build.kde.org/job/Frameworks/job/kirigami/job/kf5-qt5%20WindowsMSVCQt5.15/461/ Project: kf5-qt5 WindowsMSVCQt5.15 Date of build: Thu, 09 Sep 2021 13:11:15 + Build duration: 4 min 16 sec and counting JUnit Tests Name: projectrootC_.CI.Job_Build Failed: 0 test(s), Passed: 12 test(s), Skipped: 0 test(s), Total: 12 test(s)
