On 04/08/14 14:27, "Thiago Macieira" <[email protected]> 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" <[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. 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 [email protected] http://lists.qt-project.org/mailman/listinfo/development
