[Development] \until (was: Re: QList)
Marc Mutz
marc.mutz at kdab.com
Sat Apr 1 17:58:06 CEST 2017
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
More information about the Development
mailing list