Add some documentation

doc/Doxyfile.extra.in

@@ -7,3 +7,5 @@ INPUT           = @CMAKE_SOURCE_DIR@/include    \
 TAGFILES        = @GEPETTO_VIEWER_DOXYGENDOCDIR@/gepetto-viewer.doxytag=@GEPETTO_VIEWER_DOXYGENDOCDIR@
 
 GENERATE_TREEVIEW      = NO
+
+EXAMPLE_PATH    = @CMAKE_SOURCE_DIR@/

include/gepetto/gui/mainwindow.hh

@@ -65,6 +65,7 @@ namespace gepetto {
 signals:
         void sendToBackground (WorkItem* item);
         void createView (QString name);
+        /// Triggered when an OSGWidget is created.
         void viewCreated (OSGWidget* widget);
         void refresh ();
         void applyCurrentConfiguration();

include/gepetto/gui/pythonwidget.hh

@@ -17,6 +17,37 @@
 
 namespace gepetto {
   namespace gui {
+    /// \defgroup plugin Plugin interfaces
+
+
+    /// \ingroup plugin
+    /// Python plugin interface
+    ///
+    /// A Python plugin is a Python module containing a class Plugin, with a
+    /// constructor taking a pointer to the MainWindow as input.
+    ///
+    /// For instance, if you have \code gepetto.gui=true \endcode in your
+    /// configuration file, then the Plugin class will be accessed via:
+    ///
+    /// \code{py}
+    /// from gepetto.gui import Plugin
+    /// pluginInstance = Plugin(mainWindow)
+    /// \endcode
+    ///
+    /// It may interact with the interface in two following ways.
+    ///
+    /// pyplugin_dockwidget Add a dock widget:
+    ///
+    /// Your plugin may inherits from class PythonQt.QtGui.QDockWidget.
+    /// In this case, an instance of the Plugin  will be added to the MainWindow
+    /// as a QDockWidget.
+    ///
+    /// pyplugin_signals Signals and slots:
+    ///
+    /// The following method will be automatically connected to Qt signals:
+    /// \li MainWindow::viewCreated(OSGWidget*) -> Plugin.osgWidget
+    ///
+    /// \sa See example \ref pyplugins/gepetto/gui/pythonwidget.py
     class PythonWidget : public QDockWidget
     {
       Q_OBJECT
@@ -30,7 +61,7 @@ namespace gepetto {
       ///
       /// This is mostly equivalent to running the following code in the Python
       /// console
-      /// \code[py]
+      /// \code{py}
       /// import modulename
       /// pluginInstance = modulename.Plugin(mainWindow)
       /// mainWindow.addDockWidget (1, pluginInstance)
@@ -57,6 +88,11 @@ namespace gepetto {
     public slots:
       void browseFile();
     };
+
+    /// \example pyplugins/gepetto/gui/pythonwidget.py
+    /// This is an example Python Plugin for \link hpp::gui::PythonWidget \endlink. Two classes are defined:
+    /// \b _NodeCreator and \b Plugin. Two signals are used: \a mainWindow.refresh()
+    /// and \a osgWidget.
   } // namespace gui
 } // namespace gepetto
 

include/gepetto/gui/settings.hh

@@ -12,6 +12,12 @@ namespace gepetto {
   namespace gui {
     class MainWindow;
 
+    /// Settings manager for the interface.
+    ///
+    /// This struct is responsible for parsing configuration files as follow:
+    /// - Robots file: Settings::readRobotFile()
+    /// - Environments file: Settings::readEnvFile()
+    /// - Configuration file: Settings::readSettingFile()
     struct Settings {
       std::string configurationFile;
       std::string predifinedRobotConf;
@@ -52,11 +58,33 @@ namespace gepetto {
 
       std::ostream& print (std::ostream& os);
 
-    private:
+      /// \note Prefer using Settings::fromFiles()
       void readRobotFile ();
+      /// \note Prefer using Settings::fromFiles()
       void readEnvFile ();
+      /// Read the settings file.
+      ///
+      /// Here is the syntax:
+      /// \code
+      /// ; Comments starts with a ; You may uncomment to see the effect.
+      ///
+      /// [plugins]
+      /// ; Put a list of C++ plugins followed by '=true'. For instance, HPP users may have
+      /// ; libhppwidgetsplugin.so=true
+      /// ; libhppcorbaserverplugin.so=true
+      ///
+      /// [pyplugins]
+      /// ; Put a list of Python plugins followed by '=true'. For instance, the example plugin can be loaded with
+      /// ; gepetto.plugin=true
+      ///
+      /// ; WARNING: Any comment in this file may be removed by the GUI if you regenerate a configuration file.
+      /// \endcode
+      /// \note Details on plugin interface can be found in PluginInterface, resp. PythonWidget, class
+      /// for C++, resp. Python, plugins.
+      /// \note Prefer using Settings::fromFiles()
       void readSettingFile ();
 
+    private:
       void writeRobotFile ();
       void writeEnvFile ();
       void writeSettingFile ();

pyplugins/CMakeLists.txt

@@ -17,7 +17,7 @@
 
 INSTALL(
   FILES
-  ${CMAKE_CURRENT_SOURCE_DIR}/gepetto/gui/plugin.py
+  ${CMAKE_CURRENT_SOURCE_DIR}/gepetto/gui/pythonwidget.py
   ${CMAKE_CURRENT_SOURCE_DIR}/gepetto/gui/__init__.py
   DESTINATION ${PYTHON_SITELIB}/gepetto/gui
   )

pyplugins/gepetto/gui/__init__.py

-from plugin import Plugin
+from pythonwidget import Plugin

pyplugins/gepetto/gui/plugin.py → pyplugins/gepetto/gui/pythonwidget.py

@@ -58,7 +58,10 @@ class _NodeCreator (QtGui.QWidget):
         self.client.gui.addToGroup(str(self.nodeName.text), str(self.groupNodes.currentText))
 
 class Plugin(QtGui.QDockWidget):
-    """ Example of plugin of the Gepetto Viewer GUI """
+    """
+    Example of plugin of the Gepetto Viewer GUI. This can interact with
+    PythonWidget C++ class.
+    """
     def __init__ (self, mainWindow, flags = None):
         if flags is None:
             super(Plugin, self).__init__ ("Gepetto Viewer plugin", mainWindow)