Re: [Development] \until (was: Re: QList)
>I also don't see how you would represent the replacement of two (or more)
>overloads with a single function, unless you also propose the (welcome) option
>to document all overloads of a function in a single apidox block.
You can already do that. For example, I'm about to commit this in qimage.cpp:
/*!
\fn QImage QImage::rgbSwapped() const &
\fn QImage QImage::rgbSwapped() &&
Returns a QImage in which the values of the red and blue
components of all pixels have been swapped, effectively converting
an RGB image to an BGR image.
The original QImage is not changed.
\sa {QImage#Image Transformations}{Image Transformations}
*/
>The markup you propose below is going to cause a lot of code churn, I think.
>With \until, you just add a line to an existing apidox block.
There would be a lot of code churn, but I think it would almost all be
automatically generated.
I'm proposing to add an output generator to qdoc that generates history files
automatically. For class QWidget, there exists qwidget.h and qwidget.cpp. I'm
proposing to add the possibility of there being a qwidget.hist, which would
actually be a .qdoc file, i.e. it only contains qdoc comments. qwidget.hist
would be created this way:
First, run qdoc -history, which tells qdoc to just compare two versions of each
class in Qt, and if a class has history (because the qdoc comment for a
particular function is not the same in both versions), then either create the
history file for the class if it doesn't exist (because the class has no
history yet) or update the history file, if it does exist, with the new history.
So when we release Qt 5.9, we want to create or update the history files for
5.9 by running qdoc -history in Qt-5.9 and comparing the documentation for each
class in 5.9 to to the same documentation in 5.8. So we also have to pass the
path to the 5.8 tree:
qdoc -history ~/depot/qt-5.8
qdoc then runs as usual for each module in Qt-5.9 to build its documentation
tree for the entire module. But it doesn't generate the html files for the
module. Instead, it builds a second documentation tree for the module for
Qt-5.8 Now qdoc has two documentation trees for QtCore, say, one for 5.9 and
one for 5.8.
Next, qdoc traverses the tree for 5.9. For each member function of each class,
it finds the same function in the tree for 5.8. It compares the two qdoc
comments to see if the documentation has changed. If the documentation for a
member function of QWidget has changed, then it looks for qwidget.hist for
Qt-5.9. If that file does not exist, qdoc creates it and adds a \history block
to it containing the qdoc comment from the Qt-5.8 tree. It would add a \fn
command to this comment if it wasn't already there. If qwidget.hist already
exists, qdoc just adds the new history comment to the file. Each history
comment would be marked with the Qt version it came from.
Once qwidget.hist exists, it becomes a permanent part of the documentation, so
after qdoc -history runs, I have to use git to add and commit the new .hist
files, but qdoc can give me a list of those. From then on, qwidget.hist can be
updated both manually and automatically with qdoc -hist.
And we could repeatedly run qdoc -history over successive versions of Qt 5 to
generate each function's complete history in Qt 5. But it wouldn't work for Qt
4 because of modularization.
When qdoc later generates the html files for 5.9, it generates
qwidget-history.html, which would render the complete history of each member
function of QWidget. On the class reference html page for QWidget, the
documentation for each member function would show a link to the functions
history, if it exists.
Maybe this is overkill? What do we want to achieve with the concept of a
functions "history" ?
martin
From: Development <development-bounces+martin.smith=qt...@qt-project.org> on
behalf of Marc Mutz <marc.m...@kdab.com>
Sent: Monday, April 3, 2017 9:33:35 AM
To: development@qt-project.org
Subject: Re: [Development] \until (was: Re: QList)
On Saturday 01 April 2017 18:26:34 Martin Smith wrote:
> >One option would be to put these functions into a page like the obsolete
> >
> >members, say "historic members".
>
> I like this idea much better than trying to use combinations of \since and
> \until.
The rendering of the information is completely independent of the markup. So
you can have that historic members page with any form of markup.
The markup you propose below is going to cause a lot of code churn, I think.
With \until, you just add a line to an existing apidox block.
I also don't see how you would represent the replacement of two (or more)
overloads with a single function, unless you also propose the (welcome) option
to document all overloads of a function in a single apidox block.
Thanks,
Marc
>
> In the function comme
Re: [Development] \until (was: Re: QList)
On Saturday 01 April 2017 18:26:34 Martin Smith wrote: > >One option would be to put these functions into a page like the obsolete > > > >members, say "historic members". > > I like this idea much better than trying to use combinations of \since and > \until. The rendering of the information is completely independent of the markup. So you can have that historic members page with any form of markup. The markup you propose below is going to cause a lot of code churn, I think. With \until, you just add a line to an existing apidox block. I also don't see how you would represent the replacement of two (or more) overloads with a single function, unless you also propose the (welcome) option to document all overloads of a function in a single apidox block. Thanks, Marc > > In the function comment, after the current description, there can be > multiple \history sections: > > > \history myFunction(oldType *param) > > \since 4.8 > > > description of myFunction() in Qt 4.8 > > \endhistory > > > \history myFunction(oldType *param, anotherType anotherParam) > > \since 5.2 > > > description of myFunction in Qt 5.2. > > \endhistory > > > From: Development <development-bounces+martin.smith=qt...@qt-project.org> > on behalf of Marc Mutz <marc.m...@kdab.com> Sent: Saturday, April 1, 2017 > 5:58:06 PM > To: development@qt-project.org > Subject: [Development] \until (was: Re: QList) > > On 2017-04-01 08:32, Martin Smith wrote: > > But about the indirectly proposed until command. What is it supposed > > to do? Are we setting a policy of announcing the version when a class > > or function will be removed? > > Let's look at QSharedPointer::create(): > > It started out with no arguments, so you could only default-construct T. > > \fn QSharedPointer::create() > \since 4.8 # I'm making these number up > > Then, we added one argument, but it was taken by const-&. That's an > overload: > > \fn QSharedPointer::create() > \since 4.8 > > \fn QSharedPointer::create(const Arg ) > \overload > \since 5.1 # made up > > (empty line separates apidox comment blocks). > > And finally, we went for variadic templates, replacing both overloads: > > \fn QSharedPointer::create(Args &&...args) > \since 5.8 > > I now wrote in prose what the situation was in versions prior to 5.8. > With \until, we'd keep the old docs: > > \fn QSharedPointer::create() > \since 4.8 > \until 5.7 > > \fn QSharedPointer::create(const Arg ) > \overload > \since 5.1 # made up > \until 5.7 > > \fn QSharedPointer::create(Args &&...args) > \overload > \since 5.8 > > How we render that in the docs is another question. cppreference.com is > one example. But probably not applicable to our layout, since they use > one page per set of overloaded functions, not one for the whole class. > > One option would be to put these functions into a page like the obsolete > members, say "historic members". > > Makes sense? > > Thanks, > Marc > ___ > Development mailing list > Development@qt-project.org > http://lists.qt-project.org/mailman/listinfo/development -- Marc Mutz <marc.m...@kdab.com> | Senior Software Engineer KDAB (Deutschland) GmbH & Co.KG, a KDAB Group Company Tel: +49-30-521325470 KDAB - The Qt, C++ and OpenGL Experts ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
Re: [Development] \until (was: Re: QList)
>One option would be to put these functions into a page like the obsolete >members, say "historic members". I like this idea much better than trying to use combinations of \since and \until. In the function comment, after the current description, there can be multiple \history sections: \history myFunction(oldType *param) \since 4.8 description of myFunction() in Qt 4.8 \endhistory \history myFunction(oldType *param, anotherType anotherParam) \since 5.2 description of myFunction in Qt 5.2. \endhistory From: Development <development-bounces+martin.smith=qt...@qt-project.org> on behalf of Marc Mutz <marc.m...@kdab.com> Sent: Saturday, April 1, 2017 5:58:06 PM To: development@qt-project.org Subject: [Development] \until (was: Re: QList) On 2017-04-01 08:32, Martin Smith wrote: > But about the indirectly proposed until command. What is it supposed > to do? Are we setting a policy of announcing the version when a class > or function will be removed? Let's look at QSharedPointer::create(): It started out with no arguments, so you could only default-construct T. \fn QSharedPointer::create() \since 4.8 # I'm making these number up Then, we added one argument, but it was taken by const-&. That's an overload: \fn QSharedPointer::create() \since 4.8 \fn QSharedPointer::create(const Arg ) \overload \since 5.1 # made up (empty line separates apidox comment blocks). And finally, we went for variadic templates, replacing both overloads: \fn QSharedPointer::create(Args &&...args) \since 5.8 I now wrote in prose what the situation was in versions prior to 5.8. With \until, we'd keep the old docs: \fn QSharedPointer::create() \since 4.8 \until 5.7 \fn QSharedPointer::create(const Arg ) \overload \since 5.1 # made up \until 5.7 \fn QSharedPointer::create(Args &&...args) \overload \since 5.8 How we render that in the docs is another question. cppreference.com is one example. But probably not applicable to our layout, since they use one page per set of overloaded functions, not one for the whole class. One option would be to put these functions into a page like the obsolete members, say "historic members". Makes sense? Thanks, Marc ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development ___ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
