Update three documentation

Polyhedron/demo/Polyhedron/Plugins/PCA/Basic_generator_plugin.cpp

@@ -53,19 +53,19 @@ public :
 
 
     QMenu* menuFile = mw->findChild<QMenu*>("menuFile");
-    QMenu* menu = new QMenu(tr("Add &basic objets"), menuFile);
+    QMenu* menu = new QMenu(tr("Add &Basic Objets"), menuFile);
     QAction* actionLoad = mw->findChild<QAction*>("actionLoadPlugin");
     menuFile->insertMenu(actionLoad, menu);
 
 
-    QAction* actionPrism       = new QAction("Create prism", mw);
-    QAction* actionSphere      = new QAction("Create sphere", mw);
-    QAction* actionPyramid     = new QAction("Create pyramid", mw);
-    QAction* actionHexahedron  = new QAction("Create hexahedron", mw);
-    QAction* actionTetrahedron = new QAction("Create tetrahedron", mw);
-    QAction* actionGrid        = new QAction("Create grid", mw);
-    QAction* actionPointSet    = new QAction("Create point set", mw);
-    QAction* actionPolyline    = new QAction("Create polyline", mw);
+    QAction* actionPrism       = new QAction("Create Prism", mw);
+    QAction* actionSphere      = new QAction("Create Sphere", mw);
+    QAction* actionPyramid     = new QAction("Create Pyramid", mw);
+    QAction* actionHexahedron  = new QAction("Create Hexahedron", mw);
+    QAction* actionTetrahedron = new QAction("Create Tetrahedron", mw);
+    QAction* actionGrid        = new QAction("Create Grid", mw);
+    QAction* actionPointSet    = new QAction("Create Point Set", mw);
+    QAction* actionPolyline    = new QAction("Create Polyline", mw);
 
 
 

Polyhedron/demo/Polyhedron/Plugins/PCA/Basic_generator_widget.ui

@@ -1052,7 +1052,7 @@ QGroupBox::title {
       </widget>
       <widget class="QWidget" name="pointTab">
        <attribute name="title">
-        <string>Point set</string>
+        <string>Point Set</string>
        </attribute>
        <layout class="QVBoxLayout" name="verticalLayout_5">
         <item>

Three/demo/Three/Example_plugin/Basic_item_plugin.cpp

@@ -8,7 +8,7 @@
 #include "CGAL/Three/Scene_group_item.h"
 #include "Scene_plane_item.h"
 
-//This plugin crates an action in Operations that displays the name of the selected item,
+//This plugin creates an action in Operations that displays the name of the selected item,
 //adds a scene_plane_item to the scene, and adds the selected item and the plane to a new group.
 class BasicItemPlugin :
     public QObject,
@@ -55,7 +55,7 @@ private Q_SLOTS:
 
   void helloWorld()
   { //! [use]
-    //get a reference to the selected item.
+    //gets a reference to the selected item.
     CGAL::Three::Scene_item *item = scene->item(scene->mainSelectionIndex());
     messageInterface->information(QString("The selected item's name is  : %1").arg(item->name()));
     //! [use]
@@ -68,11 +68,11 @@ private Q_SLOTS:
     scene->addItem(new_item);
     //! [additem]
     //! [group]
-    //Create a new group
+    //Creates a new group
     Scene_group_item *group = new Scene_group_item("New group");
-    //add it to the scene
+    //adds it to the scene
     scene->addItem(group);
-    //Then give it its children
+    //Then gives it its children
     scene->changeGroup(item, group);
     scene->changeGroup(new_item,group);
     //! [group]

Three/demo/Three/Example_plugin/Basic_plugin.cpp

@@ -42,7 +42,7 @@ class BasicPlugin :
   Q_INTERFACES(CGAL::Three::Polyhedron_demo_plugin_interface)
   Q_PLUGIN_METADATA(IID "com.geometryfactory.PolyhedronDemo.PluginInterface/1.0")
 public:
-  //decides if the plugin's actions will be displayed or not.
+  //decides if the plugin actions will be displayed or not.
   bool applicable(QAction*) const Q_DECL_OVERRIDE
   {
     return true;
@@ -57,7 +57,6 @@ class BasicPlugin :
   {
     //gets the reference to the message interface, to display text in the console widget
     this->messageInterface = mi;
-    //get the references
     this->scene = sc;
     this->mw = mainWindow;
 

Three/demo/Three/Example_plugin/Dock_widget_plugin.cpp

@@ -19,7 +19,7 @@ class DockWidget :
   }
 };
 //! [dock]
-//This plugin crates an action in Operations that creates a DOckWidget to display a number in the 'console' dockwidet.
+//This plugin creates an action in Operations that creates a DockWidget to display a number in the 'console' dockwidet.
 class BasicPlugin :
     public QObject,
     public CGAL::Three::Polyhedron_demo_plugin_helper
@@ -28,7 +28,7 @@ class BasicPlugin :
   Q_INTERFACES(CGAL::Three::Polyhedron_demo_plugin_interface)
   Q_PLUGIN_METADATA(IID "com.geometryfactory.PolyhedronDemo.PluginInterface/1.0")
 public:
-  //decides if the plugin's actions will be displayed or not.
+  //decides if the plugin actions will be displayed or not.
   bool applicable(QAction*) const Q_DECL_OVERRIDE
   {
     return true;
@@ -44,7 +44,6 @@ class BasicPlugin :
   {
     //gets the reference to the message interface, to display text in the console widget
     this->messageInterface = mi;
-    //get the references
     this->scene = sc;
     this->mw = mw;
 

Three/demo/Three/Example_plugin/Example_plugin.cpp

@@ -18,7 +18,7 @@
 #  define SCENE_TRIANGLE_ITEM_EXPORT Q_DECL_IMPORT
 #endif
 
-class Scene_triangle_item : public CGAL::Three::Scene_item
+class SCENE_TRIANGLE_ITEM_EXPORT Scene_triangle_item : public CGAL::Three::Scene_item
 {
 
   Q_OBJECT
@@ -145,11 +145,11 @@ void Scene_triangle_item::initializeBuffers(CGAL::Three::Viewer_interface *viewe
 
   }
 
-//once the buffers are fill, we can empty the vectors to optimize memory consumption
+  //once the buffers are fill, we can empty the vectors to optimize memory consumption
   nb_pos = vertices.size();
   vertices.resize(0);
-  //"Swap trick" insures that the memory is indeed freed and not kept available
-  std::vector<float>(vertices).swap(vertices);
+  //insures that the memory is indeed freed and not kept available
+  vertices.shrink_to_fit();
   are_buffers_filled = true;
 }
 //! [fillbuffers]
@@ -169,7 +169,7 @@ class Q_DECL_EXPORT Polyhedron_demo_example_plugin :
 public :
   // Adds an action to the menu and configures the widget
   void init(QMainWindow* mainWindow, CGAL::Three::Scene_interface* scene_interface, Messages_interface*) Q_DECL_OVERRIDE{
-    //get the references
+    //gets the references
     this->scene = scene_interface;
     this->mw = mainWindow;
 

Three/demo/Three/Example_plugin/Group_item_plugin.cpp

@@ -8,7 +8,7 @@
 #include "Scene_plane_item.h"
 #include <CGAL/Three/Scene_group_item.h>
 
-//This plugin crates an action in Operations that displays "Hello World" in the 'console' dockwidet.
+//This plugin creates an action in Operations that creates a plane item and adds it to a group.
 class GroupItemPlugin :
     public QObject,
     public CGAL::Three::Polyhedron_demo_plugin_interface
@@ -17,7 +17,7 @@ class GroupItemPlugin :
   Q_INTERFACES(CGAL::Three::Polyhedron_demo_plugin_interface)
   Q_PLUGIN_METADATA(IID "com.geometryfactory.PolyhedronDemo.PluginInterface/1.0")
 public:
-  //This plugin is only applicable if there is at exactly one selected item.
+  //This plugin is always applicable .
   bool applicable(QAction*) const
   {
     return true;
@@ -30,19 +30,19 @@ class GroupItemPlugin :
   //this acts like a constructor for the plugin. It gets the references to the mainwindow and the scene, and connects the action.
   void init(QMainWindow* mainWindow, CGAL::Three::Scene_interface* sc  )
   {
-    //get the references
+    //gets the references
     this->scene = sc;
     this->mw = mainWindow;
 
     //creates the action
-    QAction *actionHelloWorld= new QAction(QString("Hello World"), mw);
+    QAction *actionMakeGroup= new QAction(QString("Create Group"), mw);
     //specifies the subMenu
-    actionHelloWorld->setProperty("submenuName", "Basic");
+    actionMakeGroup->setProperty("submenuName", "Basic");
     //links the action
-    if(actionHelloWorld) {
-      connect(actionHelloWorld, SIGNAL(triggered()),
-              this, SLOT(helloWorld()));
-      _actions << actionHelloWorld;
+    if(actionMakeGroup) {
+      connect(actionMakeGroup, SIGNAL(triggered()),
+              this, SLOT(makeGroup()));
+      _actions << actionMakeGroup;
     }
   }
 
@@ -55,7 +55,7 @@ class GroupItemPlugin :
 private Q_SLOTS:
 
 
-  void helloWorld()
+  void makeGroup()
   {
     //creates an item
     Scene_plane_item *child = new Scene_plane_item(scene);

Three/doc/Three/Three.txt

@@ -204,7 +204,7 @@ Once your code is written, you will need to link the item's library to your plug
 \subsubsection exampleCreatingANewTypeItem Creating a new type of item
 
 If you cannot use an existing type of item, like the Scene_polyhedron_item or the Scene_c3t3_item for your plugin, you will have to create one, by deriving CGAL::Three::Scene_item.\n
-An item is simply a graphic representation of a geometric data set. You need to compute this data, and to display it in CGAL::Three::Scene_item#draw.
+An item is simply a graphic representation of a geometric data set. You need to compute this data, and to display it in `CGAL::Three::Scene_item::draw(CGAL::Three::Viewer_interface*)const`.
 
 \snippet Three/Example_plugin/Example_plugin.cpp itemdeclaration
 
@@ -229,10 +229,10 @@ The code above gets a ShaderProgram, that holds the characteristics of the displ
 
 <b>  - Displaying the data </b>
 
-[draw()]: @ref CGAL::Three::Scene_item#draw
-[drawPoints()]: @ref CGAL::Three::Scene_item#drawPoints
-[drawEdges()]: @ref CGAL::Three::Scene_item#drawEdges
-Originally, it's the viewer that requires displaying. It calls the scene, that calls each visible item's [draw()],[drawEdges()] and [drawPoints()] functions individually.
+[draw()]: @ref CGAL::Three::Scene_item::draw(CGAL::Three::Viewer_interface*)const
+[drawPoints()]: @ref CGAL::Three::Scene_item::drawPoints(CGAL::Three::Viewer_interface*)const
+[drawEdges()]: @ref CGAL::Three::Scene_item::drawEdges(CGAL::Three::Viewer_interface*)const
+Originally, it's the viewer that requires displaying. It calls the scene, that calls each visible item's [draw()], [drawEdges()] and [drawPoints()] functions individually.
 Therefore, this is in those functions that the display of the data must be handled :
 
 \snippet Three/Example_plugin/Example_plugin.cpp draw

Three/include/CGAL/Three/Polyhedron_demo_io_plugin_interface.h

@@ -64,7 +64,7 @@ class Polyhedron_demo_io_plugin_interface
   //!This must be overriden.
   virtual bool canSave(const Scene_item*) = 0;
   //!Saves the item in the file corresponding to the path
-  //!contained in fileinfo. Returns false if error.
+  //!contained in fileinfo. Returns `false` if error.
   //! This must be overriden.
   virtual bool save(const Scene_item*, QFileInfo fileinfo) = 0;
 };

Three/include/CGAL/Three/Polyhedron_demo_plugin_helper.h

@@ -87,9 +87,9 @@ class SCENE_ITEM_EXPORT Polyhedron_demo_plugin_helper
    */
   void autoConnectActions();
 protected:
-  //!The reference to the scene
+  //The reference to the scene
   CGAL::Three::Scene_interface* scene;
-  //!The reference to the main window
+  //The reference to the main window
   QMainWindow* mw;
 };
 }

Three/include/CGAL/Three/Polyhedron_demo_plugin_interface.h

@@ -44,27 +44,25 @@ class Polyhedron_demo_plugin_interface
 public:
   //! \brief Initializes the plugin
   //! This function acts like a constructor. This is where the attributes must be initialized.
-  //! The Message_interface allows to print warnings or errors on the screen and the `Console` widget.
+  //! The `Messages_interface` allows to print warnings or errors on the screen and the Console widget.
   virtual void init(QMainWindow* , CGAL::Three::Scene_interface* , Messages_interface*) = 0;
 
   //! \brief Indicates if an action is usable or not.
   //! This function usually tests the type of the selected item to determine if `action` can be applied to it,
   //! but not necessarly.
-  //! @returns \c true if `action` can be called in the current state, \c false
+  //! @returns  `true` if `action` can be called in the current state, `false`
   //! otherwise
   virtual bool applicable(QAction* action) const = 0;
-  //!Contains all the plugin's actions.
+  //!Contains all the actions of the plugin.
   virtual QList<QAction*> actions() const = 0;
   //!\brief Is called when the application is closed.
   //! Override this function if you need to perform a specific action
-  //! when the application is closed, like hide the widgets if you don't want
-  //! their visibility to be saved.
+  //! when the application is closed, like hiding the widgets if you don't want
+  //! their visibility state to be saved.
   virtual void closure() {
  }
-protected :
 };
-}
-}
+}}
 Q_DECLARE_INTERFACE(CGAL::Three::Polyhedron_demo_plugin_interface,
                     "com.geometryfactory.PolyhedronDemo.PluginInterface/1.0")
 

Three/include/CGAL/Three/Scene_draw_interface.h

@@ -38,36 +38,37 @@ class Scene_draw_interface {
 public:
   virtual ~Scene_draw_interface(){}
 
-  /*! Is called by Viewer::initializeGL(). Allows all the initialization
+  /*! Is called by `Viewer::initializeGL()`. Allows all the initialization
    * of OpenGL code that needs a context.
    */
   virtual void initializeGL() = 0;
 
   //! \brief Draws the items.
-  //! It is called by Viewer::draw().
+  //! It is called by `Viewer::draw()`.
   virtual void draw(CGAL::Three::Viewer_interface*) = 0;
   //!\brief draws the scene in a hidden frame to perform picking.
-  //! Is called by Viewer::drawWithNames().
+  //! Is called by `Viewer::drawWithNames()`.
   virtual void drawWithNames(CGAL::Three::Viewer_interface*) = 0;
-  //!Pick the point `e` on the screen.
+  //!Performs picking on the point `e` on the screen.
   virtual void setPickedPixel(const QPoint &e) = 0;
   //! \brief Manages the key events.
   //! Override this function to perform actions when keys are pressed.
-  //! @returns true if the keyEvent executed well.
-  //!
+  //! @returns `true` if `e` executed well.
   virtual bool keyPressEvent(QKeyEvent* e) = 0;
   //!\brief print theTextItems.
   virtual void printPrimitiveId(QPoint point, CGAL::Three::Viewer_interface*) = 0;
   //!\brief update theTextItems.
   virtual void updatePrimitiveIds(CGAL::Three::Viewer_interface* , CGAL::Three::Scene_item*) = 0;
 
   /*!
-   * \brief checks if the text at position (x,y,z) is visible or not.
-   * \param x the X coordinate of theTextItem's position.
-   * \param y the Y coordinate of theTextItem's position.
-   * \param z the Z coordinate of theTextItem's position.
+   * \brief checks if the point at position (x,y,z) in World Coordinates is visible or not.
+   * A point is considered visible if there is no face between the camera and the point.
+   * This is typically used to test if an index should be displayed or not.
+   * \param x the X coordinate of the point.
+   * \param y the Y coordinate of the point.
+   * \param z the Z coordinate of the point.
    * \param viewer the viewer used to display the Scene.
-   * \return true if the TextItem is visible. */
+   * \return `true` if the point is visible. */
   virtual bool  testDisplayId(double x, double y, double z, CGAL::Three::Viewer_interface* viewer) = 0;
 
   ///\brief displays all the vertices ids if there are less than max_textItems.
@@ -78,8 +79,7 @@ class Scene_draw_interface {
   virtual void printFaceIds(CGAL::Three::Viewer_interface*) = 0;
   ///\brief displays all the primitive ids if there are less than max_textItems.
   virtual void printAllIds(CGAL::Three::Viewer_interface*) = 0;
-
-  //!\brief moves the camera orthogonally to the picked sface.
+  //!\brief moves the camera orthogonally to the picked face.
   //!
   //! \param point the picked point
   //! \param viewer the active viewer