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

Martin Smith Martin.Smith at qt.io
Sat Apr 1 18:26:34 CEST 2017


>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.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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20170401/1e1cbfa7/attachment.html>


More information about the Development mailing list