[Development] \until (was: Re: QList)

[Martin Smith]

>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.io at qt-project.org> on behalf of Marc Mutz <marc.mutz at kdab.com>
Sent: Monday, April 3, 2017 9:33:35 AM
To: development at 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 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.io at qt-project.org>
> on behalf of Marc Mutz <marc.mutz at kdab.com> Sent: Saturday, April 1, 2017
> 5:58:06 PM
> To: development at 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<T>::create():
>
> It started out with no arguments, so you could only default-construct T.
>
>     \fn QSharedPointer<T>::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<T>::create()
>     \since 4.8
>
>     \fn QSharedPointer<T>::create(const Arg &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<T>::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<T>::create()
>     \since 4.8
>     \until 5.7
>
>     \fn QSharedPointer<T>::create(const Arg &arg)
>     \overload
>     \since 5.1 # made up
>     \until 5.7
>
>     \fn QSharedPointer<T>::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 at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/development

--
Marc Mutz <marc.mutz at 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 at qt-project.org
http://lists.qt-project.org/mailman/listinfo/development