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" <[email protected]> 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 _______________________________________________ Development mailing list [email protected] http://lists.qt-project.org/mailman/listinfo/development
