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

[Glen Mabey]

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>