STYLE: Add comments.

Libs/Core/ctkModelTester.h

@@ -35,7 +35,7 @@ class QAbstractItemModel;
 class ctkModelTesterPrivate;
 
 ///
-/// ctkModelTester is a tool that test any QAbstractItemModel
+/// ctkModelTester is a tool that tests 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.

Libs/Widgets/ctkColorPickerButton.h

@@ -31,7 +31,7 @@
 ///
 /// ctkColorPickerButton is a QPushButton that refers to a color. The color 
 /// and the name of the color (i.e. #FFFFFF) are displayed on the button.
-/// When clicked, a color dialog shows up to select a new color 
+/// When clicked, a color dialog pops up to select a new color 
 /// for the QPushButton. 
 class CTK_WIDGETS_EXPORT ctkColorPickerButton : public QPushButton
 {

Libs/Widgets/ctkDirectoryButton.cpp

@@ -42,6 +42,7 @@ public:
 #else
   ctkDirectoryButton::Options DialogOptions;
 #endif
+  // TODO expose DisplayAbsolutePath into the API
   bool         DisplayAbsolutePath;
 };
 

Libs/Widgets/ctkDirectoryButton.h

@@ -30,6 +30,10 @@
 #include "CTKWidgetsExport.h"
 class ctkDirectoryButtonPrivate;
 
+/// ctkDirectoryButton is a QPushButton to select a directory path.
+/// The absolute path is displayed on the button. When clicked, a
+/// file dialog pops up to select a new directory path.
+/// \sa QPushButton, QDir
 class CTK_WIDGETS_EXPORT ctkDirectoryButton: public QWidget
 {
   Q_OBJECT
@@ -47,21 +51,28 @@ public:
 #if QT_VERSION < 0x040603
   // QFileDialog::Options is not a meta-type, we need to create our own.
   enum Option
-    {
-      ShowDirsOnly          = 0x00000001,
-      DontResolveSymlinks   = 0x00000002,
-      DontConfirmOverwrite  = 0x00000004,
-      DontUseSheet          = 0x00000008,
-      DontUseNativeDialog   = 0x00000010,
-      ReadOnly              = 0x00000020,
-      HideNameFilterDetails = 0x00000040
-    };
+  {
+    ShowDirsOnly          = 0x00000001,
+    DontResolveSymlinks   = 0x00000002,
+    DontConfirmOverwrite  = 0x00000004,
+    DontUseSheet          = 0x00000008,
+    DontUseNativeDialog   = 0x00000010,
+    ReadOnly              = 0x00000020,
+    HideNameFilterDetails = 0x00000040
+  };
   Q_DECLARE_FLAGS(Options, Option)
 #endif
+
+  /// Constructor
+  /// Creates a default ctkDirectoryButton that points to the application
+  /// current directory.
   ctkDirectoryButton(QWidget * parent = 0);
+  /// Constructor
+  /// Creates a ctkDirectoryButton that points to the given directory path
   ctkDirectoryButton(const QString& directory, QWidget * parent = 0);
   ctkDirectoryButton(const QIcon& icon, const QString& directory, QWidget * parent = 0);
 
+  /// Set/get the current directory
   void setDirectory(const QString& directory);
   QString directory()const;
 
@@ -71,6 +82,8 @@ public:
   void setCaption(const QString& caption);
   const QString& caption()const;
 
+  /// Options of the file dialog pop up.
+  /// \sa QFileDialog::getExistingDirectory
 #if QT_VERSION >= 0x040603
   void setOptions(const QFileDialog::Options& options);
   const QFileDialog::Options& options()const;
@@ -80,13 +93,17 @@ public:
 #endif
 
 public slots:
+  /// browse() opens a pop up where the user can select a new directory for the
+  /// button. browse() is automatically called when the button is clicked.
   void browse();
 
 signals:
-  ///
-  /// directoryChanged is emitted when the current directory changes
-  ///if you want a directoryChanged signal as a utility. Feel free to add it
+  /// directoryChanged is emitted when the current directory changes.
+  /// Programatically or by the user via the file dialog that pop up when 
+  /// clicking on the button.
   void directoryChanged(const QString&);
+  /// directorySelected() is emitted anytime the current directory is set
+  /// (even if the new directory is the same than the current value)
   void directorySelected(const QString&);
 private:
   CTK_DECLARE_PRIVATE(ctkDirectoryButton);

Libs/Widgets/ctkFileDialog.cpp

@@ -57,6 +57,9 @@ void ctkFileDialogPrivate::init()
   Q_ASSERT(button);
   this->AcceptButtonState =
     button->isEnabledTo(qobject_cast<QWidget*>(button->parent()));
+  // TODO: catching the event of the enable state is not enough, if the user 
+  // double click on the file, the dialog will be accepted, that event should
+  // be intercepted as well
   button->installEventFilter(p);
 }
 
@@ -93,6 +96,7 @@ void ctkFileDialog::setBottomWidget(QWidget* widget, const QString& label)
 {
   QGridLayout* gridLayout = qobject_cast<QGridLayout*>(this->layout());
   QWidget* oldBottomWidget = this->bottomWidget();
+  // remove the old widget from the layout if any
   if (oldBottomWidget)
     {
     if (oldBottomWidget == widget)
@@ -115,6 +119,8 @@ void ctkFileDialog::setBottomWidget(QWidget* widget, const QString& label)
     {
     gridLayout->addWidget(widget,4, 0,1, 2);
     }
+  // The dialog button box is no longer spanned on 2 rows but on 3 rows if
+  // there is a "bottom widget" 
   QDialogButtonBox* buttonBox = this->findChild<QDialogButtonBox*>();
   Q_ASSERT(buttonBox);
   gridLayout->removeWidget(buttonBox);

Libs/Widgets/ctkFileDialog.h

@@ -30,6 +30,10 @@
 
 class ctkFileDialogPrivate;
 
+/// Customizable QFileDialog.
+/// An extra widget can be added at the bottom of the dialog
+/// under the file format combobox. The Accept button is also controllable
+/// using setAcceptButtonEnable()
 class CTK_WIDGETS_EXPORT ctkFileDialog : public QFileDialog
 {
   Q_OBJECT
@@ -37,18 +41,29 @@ class CTK_WIDGETS_EXPORT ctkFileDialog : public QFileDialog
 public:
   // Superclass typedef
   typedef QFileDialog Superclass;
-  // Constructors
+  /// Constructor
+  /// By default, behaves like a QFileDialog
+  /// \sa QFileDialog()
   explicit ctkFileDialog(QWidget *parent = 0,
               const QString &caption = QString(),
               const QString &directory = QString(),
               const QString &filter = QString());
   virtual ~ctkFileDialog();
-
+  
+  /// Add an extra widget under the file format combobox. If a label is
+  /// given, it will appear in the first column.
+  /// The widget is reparented to ctkFileDialog
   void setBottomWidget(QWidget* widget, const QString& label=QString());
+
+  /// Return the extra widget if any
   QWidget* bottomWidget()const;
 
+  /// Internally used
   bool eventFilter(QObject *obj, QEvent *event);
 public slots:
+  /// Can be used to prevent the accept button to be enabled. It's typically
+  /// a slot that can be connected to assure that the user doesn't accept the
+  /// dialog if a value is not set in the extra bottom widget.
   void setAcceptButtonEnable(bool enable);
 
 private: