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

[Marc Mutz]

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