[Development] documentation of operators on a simple class -- qfloat16

[Laszlo Papp]

Would have been useful to give a direct link to the change like others do?


On Sun, Jun 23, 2013 at 4:24 AM, Glen Mabey <glen.mabey at swri.org> wrote:

> Hello --
>
> I recently submitted qfloat16 as a new core class implementing a 16-bit
> floating point storage class.
>
> I realize that the Qt Coding Standards require that classes start with a
> capital Q, but this one behaves so much like a basic type that it seemed to
> fit in much better with qreal, qint32, and the like than QList and other
> heavy-duty classes.
>
> I also felt that the operators should not be individually documented, as
> their behavior is really determined by IEEE 754, with the one exception
> that is identified in my modifications to the comments in qglobal.cpp .
>
> However, the Qt Doc Bot did not sympathize with my feelings,
> understandably.
>
> But really I need some feedback as to whether I'm really justified in
> putting #ifndef Q_QDOC around *all* of the methods … that just seems rather
> heavy-handed.
>
> What do you think?
>
> Glen
>
> Begin forwarded message:
>
> > From: "Qt Doc Bot (Code Review)" <gerrit-noreply at qt-project.org>
> > Subject: Change in qt/qtbase[dev]: initial submission of qfloat16 as a
> global class.
> > Date: June 22, 2013 7:53:37 PM CDT
> > To: Glen Mabey <Glen.Mabey at swri.org>
> > Cc: Qt Sanity Bot <qt_sanitybot at qt-project.org>
> > Reply-To: <qt_docbot at qt-project.org>
> >
> > Qt Doc Bot has posted comments on this change.
> >
> > Change subject: initial submission of qfloat16 as a global class.
> > ......................................................................
> >
> >
> > Patch Set 1: I would prefer that you didn't submit this
> >
> > This change introduces 30 new documentation errors.
> >
> > New qdoc warnings:
> >
> > +/tmp/qdoc_Zixejb/qtbase/src/corelib/global/qfloat16.h:101: warning: No
> documentation for 'qfloat16::operator==()'
> > +/tmp/qdoc_Zixejb/qtbase/src/corelib/global/qfloat16.h:52: warning: No
> documentation for 'qfloat16::qfloat16()'
> > +/tmp/qdoc_Zixejb/qtbase/src/corelib/global/qfloat16.h:53: warning: No
> documentation for 'qfloat16::qfloat16()'
> > +/tmp/qdoc_Zixejb/qtbase/src/corelib/global/qfloat16.h:54: warning: No
> documentation for 'qfloat16::operator float()'
> > +/tmp/qdoc_Zixejb/qtbase/src/corelib/global/qfloat16.h:56: warning: No
> documentation for 'qfloat16::operator-()'
> > +/tmp/qdoc_Zixejb/qtbase/src/corelib/global/qfloat16.h:58: warning: No
> documentation for 'qfloat16::operator+()'
>
> <snip>
>
> _______________________________________________
> Development mailing list
> Development at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/development
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20130623/effb7fcd/attachment.html>