[Development] [docs/c++] How do we deal with the special member functions (copy/move ctor/assignment operator, dtor, default ctor)

[Smith Martin]

A JIRA task has been created: https://bugreports.qt-project.org/browse/QTBUG-40589

Add more examples of what you would like to see.

martin
________________________________________
From: development-bounces+martin.smith=digia.com at qt-project.org [development-bounces+martin.smith=digia.com at qt-project.org] on behalf of Knoll Lars [Lars.Knoll at digia.com]
Sent: Monday, August 04, 2014 2:46 PM
To: Thiago Macieira; development at qt-project.org
Subject: Re: [Development] [docs/c++] How do we deal with the special member functions (copy/move ctor/assignment operator, dtor, default ctor)

On 04/08/14 14:27, "Thiago Macieira" <thiago.macieira at intel.com> wrote:

>On Monday 04 August 2014 09:31:12 Marc Mutz wrote:
>> On Monday 04 August 2014 08:02:51 Knoll Lars wrote:
>> > On 02/08/14 18:21, "Thiago Macieira" <thiago.macieira at intel.com>
>>wrote:
>> > >Why do we have to document them in the first place? I hate having to
>> > >write
>> > >documentation for a destructor that simply says "frees resources
>> > >associated
>> > >with this object".
>
>> Ok, fair enough, but how, then, is a user-defined special member
>>function
>> (where user = Qt developers) different, assuming, of course, that the
>>user-
>> defined copy ctor actually copies...? It's an implementation detail
>>whether
>> the implicit version works or whether a user implementation is
>>necessary..
>> By documenting one and not the other, we either leak that information,
>>or
>> make new C++ users think that some classes - that are - aren't copyable.
>
>As I said, I'd rather not document any of them if they don't do anything
>special and don't have user-visible impacts. The fact that we had to
>document
>a few notwithstanding: we should modify qdoc so there's a way to document
>a
>type as copyable and also suppress those special constructors in the docs.
>
>> Worse: unless you look at the header file, there's no way to predict
>>whether
>> the implicitly declared, say, copy constructor is deleted or defaulted.
>>And
>> it's not as if Q_DISABLE_COPY generates any documentation.
>
>The solution is to make Q_DISABLE_COPY generate documentation and mark
>the
>type as non-copyable.
>
>> So maybe the real questions is, as Thiago said, how to document whether
>>a
>> class is a value class or polymorphic (though, of course, there are more
>> than these two: move-only classes, RAII classes (with some overlap
>>between
>> the two, etc)).
>>
>> \valueclass
>> \polymorphic
>> \raii
>> \move-only
>>
>> Or just
>>
>> \implicitdefaultctor
>> \impicitcopyctor
>> \implicitmovector
>> \implicitdtor
>> \implicitcopyassignment \____> \implicitassignment
>> \implicitmoveassignment /
>
>I'd rather have \valueclass and Q_DISABLE_COPY. The in-between cases will
>require per-method documentation.

I’d agree with this. Qdoc could add some standard wording for a class that
can be copied (or not), and then we can get rid of the explicit
documentation for copy constructors and assignment operators. And let’s
document special cases where required.

Cheers,
Lars

_______________________________________________
Development mailing list
Development at qt-project.org
http://lists.qt-project.org/mailman/listinfo/development