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

[Marc Mutz]

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