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

[Thiago Macieira]

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.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center