Qt-interest Archive, January 2007
Model/View documentation comments
Message 1 in thread
Hi
I thought I'd offer a few comments on the model/view documentation while
it's all still fairly fresh. I know how hard it is to forget the
assumptions about knowledge one makes when writing docs.
When studying the model/view system with the intent of writing a table
model, the things I found less than ideally clear were:
QModelIndex QAbstractItemModel::parent(const QModelIndex& item)
The returned model index must have the row component set to
the parent's row number within *its* parent. Obvious
in retrospect, but quite confusing at the time.
QModelIndex QAbstractItemModel::index(int row, int column,
const QModelIndex & parent)
The row and column values in `parent' appear to be meaningless.
They are not used by the sample implementation and don't relate
to much of anything. Instead, the function appears to want the
item specified by `row' and `column' within the object pointed
to by `parent' (if valid) or otherwise the root table. Since
parent.row() and parent.column() aren't meaningful if
!parent.isValid() this makes sense, but is confusing to the
implementer. I think this needs clarification in the examples
and documentation.
In general I found the system quite well documented. My only real issue
was that in some cases the meaning of parameters was insufficiently
clearly described for someone who doesn't already know the Qt model/view
framework well. The two cases above were particularly noteworthy.
I found the explanation of the general concept of the table structure of
the model EXTREMELY simple, clear, and well executed. Most of the
example was also quite good, but I do think the system suffers for the
lack of clearer descriptions of exactly what each method the user must
implement is intended to _do_, ie the intended utility of the method
within the framework.
Hope this is of some use.
--
[ signature omitted ]
Message 2 in thread
On 31.01.07 22:52:42, Craig Ringer wrote:
> I thought I'd offer a few comments on the model/view documentation while it's
> all still fairly fresh. I know how hard it is to forget the assumptions about
> knowledge one makes when writing docs.
Please send this to qt-bugs trolltech com, this is not the right place
for bug or wishlist reports against Qt.
Andreas
--
[ signature omitted ]
Message 3 in thread
Craig Ringer wrote:
> I thought I'd offer a few comments on the model/view documentation while
> it's all still fairly fresh. I know how hard it is to forget the
> assumptions about knowledge one makes when writing docs.
>
> When studying the model/view system with the intent of writing a table
> model, the things I found less than ideally clear were:
>
> QModelIndex QAbstractItemModel::parent(const QModelIndex& item)
>
> The returned model index must have the row component set to
> the parent's row number within *its* parent. Obvious
> in retrospect, but quite confusing at the time.
Yes, it's easy to forget which item the row and column numbers are
referring to.
> QModelIndex QAbstractItemModel::index(int row, int column,
> const QModelIndex & parent)
>
> The row and column values in `parent' appear to be meaningless.
Well, they tell you about the parent's location. :-)
> They are not used by the sample implementation and don't relate
> to much of anything. Instead, the function appears to want the
> item specified by `row' and `column' within the object pointed
> to by `parent' (if valid) or otherwise the root table. Since
> parent.row() and parent.column() aren't meaningful if
> !parent.isValid() this makes sense, but is confusing to the
> implementer. I think this needs clarification in the examples
> and documentation.
This is interesting to read, but mostly because you should be subclassing
QAbstractTableModel rather than QAbstractItemModel if you are making your
own table model. However, the documentation could deal with hierarchical
(tree) models better.
> In general I found the system quite well documented. My only real issue
> was that in some cases the meaning of parameters was insufficiently
> clearly described for someone who doesn't already know the Qt model/view
> framework well. The two cases above were particularly noteworthy.
I think the problem has been that there are quite a few people who have
"grown up" with the framework who require increasingly advanced information
about it, and this tends to influence what has been documented so far.
> I found the explanation of the general concept of the table structure of
> the model EXTREMELY simple, clear, and well executed. Most of the
> example was also quite good, but I do think the system suffers for the
> lack of clearer descriptions of exactly what each method the user must
> implement is intended to _do_, ie the intended utility of the method
> within the framework.
>
> Hope this is of some use.
Yes, I think so. We've tried to highlight some of that in the examples, but
more basic function documentation could also be helpful.
Thanks for the feedback,
David
--
[ signature omitted ]
