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

[Marc Mutz]

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:
> >On Friday 01 August 2014 23:16:40 Marc Mutz wrote:
> >> That leaves the question how to deal with the documentation for these
> >> implicit  members.
> >
> >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". That much is obvious: any self-respecting destructor
> >will
> >do that and the same applies to copy and move constructors.
> >
> >What we really want is to document which objects are copyable and which
> >ones
> >aren't. And that is very simple: any object with Q_DISABLE_COPY is not
> >copyable, (almost) everything else is.
> 
> +1. I don’t see a reason to document implicitly generated methods. They
> simply do what the C++ standard defines they should do.

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.

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.

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 /

?

-- 
Qt Developer Days 2014 - October 6 - 8 at BCC, Berlin

Marc Mutz <marc.mutz at kdab.com> | Senior Software Engineer
KDAB (Deutschland) GmbH & Co.KG, a KDAB Group Company
www.kdab.com || Germany +49-30-521325470 || Sweden (HQ) +46-563-540090
KDAB - Qt Experts - Platform-Independent Software Solutions