STYLE: Add documentation to ctkModelTester

Libs/Core/ctkModelTester.h

@@ -34,27 +34,70 @@
 class QAbstractItemModel;
 class ctkModelTesterPrivate;
 
+///
+/// ctkModelTester is a tool that test any QAbstractItemModel
+/// Most of the signals fired by the model set (ctkModelTester::setModel())
+/// are connected to the tester that check their consistency with the 
+/// model contents.
+/// ctkModelTester is typically used when developing a new QAbstractItemModel
+/// or during unit tests.
 class CTK_CORE_EXPORT ctkModelTester: public QObject
 {
   Q_OBJECT
   Q_PROPERTY(bool nestedInserts READ nestedInserts WRITE setNestedInserts);
 public:
+  ///
+  /// Constructor
+  /// No model is set by default. To be tested, a model must be set using 
+  /// setModel(...)
   explicit ctkModelTester(QObject *parent = 0);
+
+  ///
+  /// Constructor that set the model to test.
+  /// A new model can later be set using setModel(...)
   ctkModelTester(QAbstractItemModel *model, QObject *parent = 0);
 
+  ///
+  /// Set the model to be tested, the model must remain valid during 
+  /// the life ctkModelTester.
   void setModel(QAbstractItemModel* model);
   QAbstractItemModel* model()const;
 
+  ///
+  /// Throw an exception when an error is found in the model.
+  /// True by default 
   void setThrowOnError(bool throwException);
   bool throwOnError()const;
  
+  ///
+  /// nestedInserts controls wether the model is allowed to make 
+  /// nested row/column insertions ( an insertion signal is fired when an 
+  /// insertion a previous insertion was not finished). A row insertion 
+  /// consists of 2  signals: rowsAboutToBeInserted and rowsInserted
+  /// It also applies for row/column suppressions. 
   void setNestedInserts(bool enable);
   bool nestedInserts()const;
 
+  ///
+  /// Test the data consistency of a QModelIndex.
+  /// Note: Only DisplayRole is checked.
   virtual void testData(const QModelIndex& index)const;
+
+  ///
+  /// Run all the tests on the model previously set in setModel(...)
   virtual void testModel()const;
+
+  ///
+  /// Run a collection of tests on a QModelIndex
   virtual void testModelIndex(const QModelIndex& index)const;
+
+  ///
+  /// Check the hierarchy consistency of a QModelIndex 
+  /// child/parent/siblings relationships
   virtual void testParent(const QModelIndex& parent)const;
+
+  /// 
+  /// Test a persistent model index
   virtual void testPersistentModelIndex(const QPersistentModelIndex& index)const;
 
 protected slots:
@@ -74,11 +117,32 @@ protected slots:
   void onRowsRemoved(const QModelIndex & parent, int start, int end);
   
 protected:
+  /// 
+  /// The logic of onColumnsAboutToBeInserted and onRowsAboutToBeInserted is 
+  /// gathered in onItemsAboutToBeInserted
   virtual void onItemsAboutToBeInserted(const QModelIndex& parent, Qt::Orientation, int start, int end);
+
+  /// 
+  /// The logic of onColumnsAboutToBeRemoved and onRowsAboutToBeRemoved is 
+  /// gathered in onItemsAboutToBeRemoved
   virtual void onItemsAboutToBeRemoved(const QModelIndex& parent, Qt::Orientation, int start, int end);
+
+  /// 
+  /// The logic of onColumnsInserted and onRowsInserted is gathered in 
+  /// onItemsInserted
   virtual void onItemsInserted(const QModelIndex& parent, Qt::Orientation, int start, int end);
+
+  /// 
+  /// The logic of onColumnsRemoved and onRowsRemoved is gathered in 
+  /// onItemsRemoved
   virtual void onItemsRemoved(const QModelIndex& parent, Qt::Orientation, int start, int end);
+
+  ///
+  /// Create a list of persistent index of all the index's children
   QList<QPersistentModelIndex> persistentModelIndexes(const QModelIndex& index)const;
+
+  ///
+  /// Utility function that process the result of a test
   virtual void test(bool result, const QString& errorString)const;
   
 private: