Merge pull request #1074 from dlyr/fix-doxy

Fix doxygen warnings

doc/basics/commandline.md

@@ -27,7 +27,7 @@ If not given on the command line, the installation directory is set by default t
 
 For command line, tested on Linux and mac OS, **for windows might need more configuration options**.
 
-Follow the usual sequence, assuming you have build dependencies as explained [here](@ref builddep):
+Follow the usual sequence, assuming you have build dependencies as explained [here](\ref builddep):
 
 ~~~{.bash}
 cmake -S Radium-Engine -B builds/radium-build-r -DCMAKE_BUILD_TYPE=Release -C installs/radium-external-r/radium-options.cmake

doc/basics/radium-as-submodule.md

@@ -36,4 +36,4 @@ In your source code:
 
 ## Detailed instructions
 
-See [CMake setup](@ref cmakeutilities) for detailed doc and Radium's cmake utilies function insights.
+See [CMake setup](\ref cmakeutilities) for detailed doc and Radium's cmake utilies function insights.

doc/concepts/forwardrenderer.md

@@ -5,7 +5,7 @@ The main renderer of Radium, implemented in the class Ra::Engine::Rendering::For
 rendering loop.
 Even if the material association to a drawable object, realized by the so called Ra::Engine::Rendering::RenderTechnique is tightly
 coupled with the main rendering loop, Plugins might define new renderers and interact differently with shader and
-materials properties (see chapter on [Materials](@ref develmaterials) ).
+materials properties (see chapter on [Materials](\ref develmaterials) ).
 
 Here is a summary of the different passes of the Ra::Engine::Rendering::ForwardRenderer
 

doc/developer/cmakeutilities.md

@@ -854,4 +854,4 @@ where `<resourcesPrefix>` corresponds to the parameter `PREFIX` used when instal
 
 ## Configuring an application plugin
 
-See [How to write your own plugin](@ref develplugin).
+See [How to write your own plugin](\ref develplugin).

doc/developer/conventions.md

@@ -6,9 +6,8 @@ Mainly inspired by <https://google-styleguide.googlecode.com/svn/trunk/cppguide.
 
 # Code style
 
-Please follow the scripts/clang-format coding style (tested `with clang-format 9.0`).
-We also provide a pre commit hook that checks the committed files are correctly formatted.
-To install both hooks and clang-format, simply run `./scripts/install-scripts-linux.sh` on linux, or adapt to your OS.
+Please follow the scripts/clang-format coding style.
+We also provide a pre-commit hook that checks the committed files are correctly formatted (see \ref pre_commit).
 
 * Indentation style : 4-spaces
 * Brace style : keep it consistent across files.
@@ -22,7 +21,8 @@ To install both hooks and clang-format, simply run `./scripts/install-scripts-li
 * use prefix increments (`++i` and not `i++`)
 * use `const` everywhere possible. use `constexpr` for const values.
 * line length should be kept at 80 (soft limit) and not exceed 120 (hard limit)
-* no need for () for a return statement.
+* no need for () for a return statement
+* document using doxygen convention, special commands with backslash \\ (e.g. `\brief` rather than `@brief`).
 
 # Headers
 

doc/developer/develWithRadium.md

@@ -7,7 +7,7 @@ Direct contributions to master are closed.
 We defer merge to master after our radium based projects (public or private) CI tests.
 To this end, please select release_candidate as a base branch of your pull requests.
 
-# Pre commit hook
+# Pre commit hook {#pre_commit}
 
 We provide a configuration file for [pre-commit](https://pre-commit.com/). Please install and use it, e.g.
 

doc/developer/material.md

@@ -52,7 +52,7 @@ must be associated with a Ra::Engine::Rendering::RenderTechnique that links to t
 To do that, the following steps must be done :
 \todo update snippets that are not available anymore.
 
-1. Create the Ra::Engine::Data::Mesh (see the [documentation about Meshes](@ref develmeshes))
+1. Create the Ra::Engine::Data::Mesh (see the [documentation about Meshes](\ref develmeshes))
 
 2. Create the Ra::Engine::Data::Material
 
@@ -62,7 +62,7 @@ to the material
 4. Create the Ra::Engine::Rendering::RenderObject and add it to the Ra::Engine::Scene::Component
 
 Note that this way of using the _Radium Material Library_ is very related to the default Radium rendering capabilities
-exposed by the [Radium forward renderer](@ref forwardRenderer).
+exposed by the [Radium forward renderer](\ref forwardRenderer).
 See the [Render technique management](#render-technique) documentation to learn how to create your own
 Ra::Engine::Rendering::RenderTechnique, potentially without associated material.
 

doc/developer/rendering.md

@@ -109,7 +109,7 @@ Help wanted for this section.
 
 # Radium Engine default rendering information
 
-See [Material management](@ref develmaterials) documentation for a complete description of the
+See [Material management](\ref develmaterials) documentation for a complete description of the
 interactions geometry, material and shader._
 
 # Potential extensions for the renderer

doc/main.md

@@ -33,6 +33,6 @@ See [this presentation](https://docs.google.com/presentation/d/12W2KXY7ctJXFIelm
 
 The documentation is structured as follow:
 
-- @ref basicsmanual : how to compile Radium and use it in your own project.
-- @ref develmanual : general topics (e.g. coding conventions) and description of the concepts found in the API of Radium.
-- @ref conceptsmanual : high level concepts used in Radium Engine
+- \ref basicsmanual : how to compile Radium and use it in your own project.
+- \ref develmanual : general topics (e.g. coding conventions) and description of the concepts found in the API of Radium.
+- \ref conceptsmanual : high level concepts used in Radium Engine

examples/DrawPrimitives/minimalapp.hpp

@@ -15,7 +15,7 @@ class MinimalApp : public QApplication
 
   public:
     /** IMPORTANT : the argc parameter must be a reference for calling the QApplication constructor
-        @see http://doc.qt.io/qt-5/qapplication.html#QApplication
+        \see http://doc.qt.io/qt-5/qapplication.html#QApplication
     */
     MinimalApp( int& argc, char** argv );
     ~MinimalApp();

examples/RawShaderMaterial/main.cpp

@@ -87,8 +87,8 @@ class MyParameterProvider : public Ra::Engine::Data::ShaderParameterProvider
 
 /**
  * Generate a quad with a ShaderMaterial attached
- * @param app
- * @return The renderObject associated to the created component.
+ * \param app
+ * \return The renderObject associated to the created component.
  */
 std::shared_ptr<Ra::Engine::Rendering::RenderObject> initQuad( Ra::Gui::BaseApplication& app ) {
     //! [Creating the quad]

examples/SimpleAnimation/main.cpp

@@ -32,7 +32,7 @@
  *   animated Blinn-Phong material to the geometry and update both the transformation and the
  *   diffuse color at each time step.
  *
- *   @note This is only for demo purpose. A more simpler approach could be :
+ *   \note This is only for demo purpose. A more simpler approach could be :
  *      - Create and add a geometry component to the Engine geometry system (like in HelloRadium)
  *      - Get the renderobject associated with this component and create an animation component
  *              that associates the RenderObject with an animation controller

src/Core/Animation/HandleArray.hpp

@@ -33,7 +33,7 @@ class RA_CORE_API HandleArray
     virtual ~HandleArray();
 
     /**
-     * @return the number of transformations
+     * \return the number of transformations
      */
     inline virtual uint size() const { return m_pose.size(); }
 
@@ -43,19 +43,19 @@ class RA_CORE_API HandleArray
     virtual void clear();
 
     /**
-     * @return the current pose in the \p MODE space.
+     * \return the current pose in the \p MODE space.
      */
     virtual const Pose& getPose( const SpaceType MODE ) const;
 
     /**
      * Set the current pose.
-     * @param pose the new pose
-     * @param MODE the space the psoe lives in
+     * \param pose the new pose
+     * \param MODE the space the psoe lives in
      */
     virtual void setPose( const Pose& pose, const SpaceType MODE );
 
     /**
-     * @return the \p i-th transformation in \p MODE space.
+     * \return the \p i-th transformation in \p MODE space.
      */
     virtual const Transform& getTransform( const uint i, const SpaceType MODE ) const;
 
@@ -65,7 +65,7 @@ class RA_CORE_API HandleArray
     virtual void setTransform( const uint i, const Transform& T, const SpaceType MODE );
 
     /**
-     * @return the Handle's name
+     * \return the Handle's name
      */
     inline Label getName() const { return m_name; }
 
@@ -75,7 +75,7 @@ class RA_CORE_API HandleArray
     inline void setName( const Label& name ) { m_name = name; }
 
     /**
-     * @return the name of the \p i-th transform.
+     * \return the name of the \p i-th transform.
      */
     inline Label getLabel( const uint i ) const;
 

src/Core/Animation/KeyFramedValue.hpp

@@ -25,7 +25,7 @@ class RA_CORE_API KeyFramedValueBase
     virtual ~KeyFramedValueBase() {}
 
     /**
-     * @returns the number of keyframes.
+     * \returns the number of keyframes.
      */
     virtual inline size_t size() const = 0;
 
@@ -95,12 +95,12 @@ class KeyFramedValue : public KeyFramedValueBase
     /// \{
 
     /**
-     * @returns the number of keyframes.
+     * \returns the number of keyframes.
      */
     inline size_t size() const override { return m_keyframes.size(); }
 
     /**
-     * @returns the collection of keyframes.
+     * \returns the collection of keyframes.
      */
     const KeyFrames& getKeyFrames() const { return m_keyframes; }
 
@@ -213,15 +213,15 @@ class KeyFramedValue : public KeyFramedValueBase
     /// \{
 
     /**
-     * @returns true if *this and \p keyframe have the exact same keyframes,
+     * \returns true if *this and \p keyframe have the exact same keyframes,
      *          false otherwise.
      */
     inline bool operator==( const KeyFramedValue& keyframe ) const {
         return ( m_keyframes == keyframe.m_keyframes );
     }
 
     /**
-     * @returns true if *this and \p keyframe do not have the exact same keyframes,
+     * \returns true if *this and \p keyframe do not have the exact same keyframes,
      *          false otherwise.
      */
     inline bool operator!=( const KeyFramedValue& keyframe ) const {

src/Core/Animation/Skeleton.hpp

@@ -51,19 +51,19 @@ class RA_CORE_API Skeleton : public HandleArray
 
     /**
      * Add a new root transform to the skeleton.
-     * @param T      the joint transform associated to the new bone
-     * @param label  the name for the new joint
-     * @return       the index of the new joint
+     * \param T      the joint transform associated to the new bone
+     * \param label  the name for the new joint
+     * \return       the index of the new joint
      */
     uint addRoot( const Transform& T = Transform::Identity(), const Label label = "" );
 
     /**
      * Add a new joint transform to the skeleton.
-     * @param parent the index of the joint's parent in the hierarchy
-     * @param T      the joint transform associated to the new bone
-     * @param MODE   SpaceType of T (either SpaceType::LOCAL or SpaceType::MODEL)
-     * @param label  the name for the new joint
-     * @return       the index of the new joint
+     * \param parent the index of the joint's parent in the hierarchy
+     * \param T      the joint transform associated to the new bone
+     * \param MODE   SpaceType of T (either SpaceType::LOCAL or SpaceType::MODEL)
+     * \param label  the name for the new joint
+     * \return       the index of the new joint
      */
     uint addBone( const uint parent,
                   const Transform& T   = Transform::Identity(),
@@ -72,9 +72,9 @@ class RA_CORE_API Skeleton : public HandleArray
 
     /**
      * Get the i-th bone endpoints in Model space.
-     * @param i             the bone index
-     * @param[out] startOut the bone's start point
-     * @param[out]  endOut   the bone's end point
+     * \param i             the bone index
+     * \param[out] startOut the bone's start point
+     * \param[out]  endOut   the bone's end point
      *
      * \note If the i-th bone is a leaf, then \p startOut == \p endOut.
      */

src/Core/Asset/Camera.hpp

@@ -224,15 +224,15 @@ class RA_CORE_API Camera
     Scalar m_zFar { 1000_ra };                     ///< Z Far plane distance
 
     /// \name Perspective projection parameters
-    ///@{
+    ///\{
     Scalar m_fov { Core::Math::PiDiv4 }; ///< Horizontal Field Of View
-    ///@}
+    ///\}
 
     /// \name Orthographic projection parameters
-    ///@{
+    ///\{
     Scalar m_xmag { 1_ra };
     Scalar m_ymag { 1_ra };
-    ///@}
+    ///\}
 };
 
 inline Core::Transform Camera::getFrame() const {

src/Core/Asset/LightData.hpp

@@ -63,7 +63,7 @@ class RA_CORE_API LightData : public AssetData
      * Copy constructor.
      * As a Light a a union like object, no default copy constructor could be generated. This will
      * take care of copying the good members of the union.
-     * @param data
+     * \param data
      */
     LightData( const LightData& data );
 
@@ -79,13 +79,13 @@ class RA_CORE_API LightData : public AssetData
 
     /**
      * Acces to the local frame of the light.
-     * @return the local frame
+     * \return the local frame
      */
     inline const Eigen::Matrix<Scalar, 4, 4>& getFrame() const;
 
     /**
      * Set the local frame of the light.
-     * @param frame the local frame
+     * \param frame the local frame
      */
     inline void setFrame( const Eigen::Matrix<Scalar, 4, 4>& frame );
 

src/Core/Asset/MaterialData.hpp

@@ -9,7 +9,7 @@ namespace Ra {
 namespace Core {
 namespace Asset {
 
-/** @brief represent material data loaded by a file loader.
+/** \brief represent material data loaded by a file loader.
  * Material data must be identified by a unique name.
  * Radium Engine reserves the following names
  *  "AbstractMaterial"  --> unknown material, might serve for error management

src/Core/Containers/VectorArray.hpp

@@ -26,7 +26,7 @@ struct VectorArrayTypeHelper : public VectorArrayTypeHelperInternal<
                                    std::is_base_of<typename Eigen::MatrixBase<V>, V>::value> {};
 
 /**
- * @brief This class implements ContainerIntrospectionInterface for AlignedStdVector.
+ * \brief This class implements ContainerIntrospectionInterface for AlignedStdVector.
  *
  * It provides Eigen::Map functionality if the underlying component allows it (i.e. fixed size).
  */
@@ -51,20 +51,20 @@ class VectorArray : public AlignedStdVector<V>, public Utils::ContainerIntrospec
     /** Inheriting constructors from std::vector */
     using AlignedStdVector<V>::AlignedStdVector;
 
-    /** @name Container Introsection implementation */
-    /// @{
+    /** \name Container Introsection implementation */
+    /// \{
     size_t getSize() const override { return this->size(); }
     size_t getNumberOfComponents() const override { return std::max( 0, NumberOfComponents ); }
     size_t getBufferSize() const override { return getSize() * sizeof( V ); }
     int getStride() const override { return sizeof( V ); }
     const void* dataPtr() const override { return this->data(); }
-    /// @}
+    /// \}
 
-    /** @name Eigen::Map getter
+    /** \name Eigen::Map getter
      * Map data to an Eigen::Matrix, only defined when NumberOfComponents > 0 (e.g. for arithmetic
      * types and fixed size eigen vectors).
      */
-    /// @{
+    /// \{
     /** Returns the array as an Eigen Matrix Map. */
     template <int N = NumberOfComponents>
     std::enable_if_t<( N > 0 ), MatrixMap> getMap() {
@@ -82,7 +82,7 @@ class VectorArray : public AlignedStdVector<V>, public Utils::ContainerIntrospec
                                TypeHelper::NumberOfComponents,
                                Eigen::Index( this->size() ) );
     }
-    /// @}
+    /// \}
 };
 
 template <typename V>