Normalized docstrings

src/basics/FractalNoise.h

@@ -8,8 +8,8 @@
 namespace paysages {
 namespace basics {
 
-/*!
+/**
- * \brief Fractal noise generator, based on a sum of simple noise functions.
+ * Fractal noise generator, based on a sum of simple noise functions.
  */
 class BASICSSHARED_EXPORT FractalNoise {
   public:
@@ -39,6 +39,11 @@ class BASICSSHARED_EXPORT FractalNoise {
 
     virtual double getBase1d(double x) const;
     virtual double getBase2d(double x, double y) const;
+    /**
+     * Base 3d noise function, returning (as much as possible) a value in the [0.5, 0.5] range.
+     *
+     * Other dimension noise (1d and 2d) can be provided, or this one will be used to simulate them.
+     */
     virtual double getBase3d(double x, double y, double z) const = 0;
 
   private:

src/basics/NoiseState.h

@@ -8,7 +8,7 @@
 namespace paysages {
 namespace basics {
 
-/*!
+/**
  * Fractal noise state, that can be saved to a file.
  *
  * This state contains the noise offsets for noise layers.

src/definition/Layers.h

@@ -11,7 +11,7 @@ namespace definition {
 typedef DefinitionNode *(*LayerConstructor)(Layers *parent, const string &name);
 
 /**
- * @brief Layers of definitions, ideally all of the same type.
+ * Layers of definitions, ideally all of the same type.
  */
 class DEFINITIONSHARED_EXPORT Layers : public DefinitionNode {
   public:

src/definition/Scenery.h

@@ -9,7 +9,7 @@ namespace paysages {
 namespace definition {
 
 /**
- * @brief Global scenery management
+ * Global scenery management
  *
  * This class contains the whole scenery definition.
  */

src/render/opengl/OpenGLVariable.h

@@ -10,8 +10,8 @@ class QImage;
 namespace paysages {
 namespace opengl {
 
-/*!
+/**
- * \brief OpenGL variable that can be bound to a uniform for shaders.
+ * OpenGL variable that can be bound to a uniform for shaders.
  */
 class OpenGLVariable final {
   public:

src/render/software/Canvas.h

@@ -10,7 +10,7 @@ namespace paysages {
 namespace software {
 
 /**
- * @brief Graphics area to draw and do compositing.
+ * Graphics area to draw and do compositing.
  *
  * Software rendering is done in portions of Canvas (in CanvasPortion class).
  * This splitting in portions allows to keep memory consumption low.

src/render/software/CanvasFragment.h

@@ -10,7 +10,7 @@ namespace paysages {
 namespace software {
 
 /**
- * @brief Representation of world coordinates projected in a canvas pixel.
+ * Representation of world coordinates projected in a canvas pixel.
  */
 class SOFTWARESHARED_EXPORT CanvasFragment {
   public:

src/render/software/CanvasLiveClient.h

@@ -7,7 +7,7 @@ namespace paysages {
 namespace software {
 
 /**
- * @brief Abstract class to receive live modifications from canvas preview.
+ * Abstract class to receive live modifications from canvas preview.
  */
 class SOFTWARESHARED_EXPORT CanvasLiveClient {
   public:

src/render/software/CanvasPixel.h

@@ -11,7 +11,7 @@ namespace paysages {
 namespace software {
 
 /**
- * @brief One pixel of a Canvas.
+ * One pixel of a Canvas.
  *
  * A pixel stores superimposed fragments (CanvasFragment), sorted by their distance to camera.
  */

src/render/software/CanvasPixelShader.h

@@ -9,7 +9,7 @@ namespace paysages {
 namespace software {
 
 /**
- * @brief Parallel worker that can work on canvas portion to resolve pixel colors.
+ * Parallel worker that can work on canvas portion to resolve pixel colors.
  *
  * This is used after the rasterization phase to compute pixel colors from the fragments stored in them.
  *

src/render/software/CanvasPreview.h

@@ -7,7 +7,7 @@ namespace paysages {
 namespace software {
 
 /**
- * @brief Smaller preview of a Canvas rendering, that can be watched live.
+ * Smaller preview of a Canvas rendering, that can be watched live.
  */
 class SOFTWARESHARED_EXPORT CanvasPreview {
   public:

src/render/software/CloudBasicLayerRenderer.cpp

@@ -30,18 +30,19 @@ static inline double _getDistanceToBorder(BaseCloudsModel *model, const Vector3
 /**
  * Go through the cloud layer to find segments (parts of the lookup that are inside the cloud).
  *
- * @param definition The cloud layer
+ * definition - The cloud layer
- * @param renderer The renderer environment
+ * renderer - The renderer environment
- * @param start Start position of the lookup (already optimized)
+ * start - Start position of the lookup (already optimized)
- * @param direction Normalized direction of the lookup
+ * direction - Normalized direction of the lookup
- * @param detail Level of noise detail required
+ * detail - Level of noise detail required
- * @param max_segments Maximum number of segments to collect
+ * max_segments - Maximum number of segments to collect
- * @param max_inside_length Maximum length to spend inside the cloud
+ * max_inside_length - Maximum length to spend inside the cloud
- * @param max_total_length Maximum lookup length
+ * max_total_length - Maximum lookup length
- * @param inside_length Resulting length inside cloud (sum of all segments length)
+ * inside_length - Resulting length inside cloud (sum of all segments length)
- * @param total_length Resulting lookup length
+ * total_length - Resulting lookup length
- * @param out_segments Allocated space to fill found segments
+ * out_segments - Allocated space to fill found segments
- * @return Number of segments found
+ *
+ * Returns the number of segments found.
  */
 int CloudBasicLayerRenderer::findSegments(BaseCloudsModel *model, const Vector3 &start, const Vector3 &direction,
                                           int max_segments, double max_inside_length, double max_total_length,

src/render/software/CloudBasicLayerRenderer.h

@@ -10,8 +10,8 @@ typedef struct CloudSegment CloudSegment;
 namespace paysages {
 namespace software {
 
-/*!
+/**
- * \brief Basic cloud layer renderer.
+ * Basic cloud layer renderer.
  *
  * This renderer simply iters through the cloud layer, collecting cloud segments.
  * It does not account for local density variations.

src/render/software/CloudsRenderer.h

@@ -10,8 +10,8 @@
 namespace paysages {
 namespace software {
 
-/*!
+/**
- * \brief Software renderer of a group of cloud layers.
+ * Software renderer of a group of cloud layers.
  */
 class SOFTWARESHARED_EXPORT CloudsRenderer : public LightFilter {
   public:
@@ -28,42 +28,42 @@ class SOFTWARESHARED_EXPORT CloudsRenderer : public LightFilter {
      */
     void setEnabled(bool enabled);
 
-    /*!
+    /**
-     * \brief Update the renderer with the bound scenery.
+     * Update the renderer with the bound scenery.
      *
      * Don't call this if another thread is currently using this renderer.
      */
     virtual void update();
 
-    /*!
+    /**
-     * \brief Get the layer renderer for a given layer.
+     * Get the layer renderer for a given layer.
      *
      * The returned renderer is managed by this object and should not be deleted.
      */
     virtual BaseCloudLayerRenderer *getLayerRenderer(unsigned int layer);
 
-    /*!
+    /**
-     * \brief Get the cloud model for a given layer.
+     * Get the cloud model for a given layer.
      *
      * The returned model is managed by this object and should not be deleted.
      */
     virtual BaseCloudsModel *getLayerModel(unsigned int layer);
 
-    /*!
+    /**
-     * \brief Override de default density model for a given layer.
+     * Override de default density model for a given layer.
      *
      * This must be called after each update().
      * Ownership of the model is taken.
      */
     virtual void setLayerModel(unsigned int layer, BaseCloudsModel *model, bool delete_old = true);
 
-    /*!
+    /**
-     * \brief Get the composited color, as applied on a base color and location.
+     * Get the composited color, as applied on a base color and location.
      */
     virtual Color getColor(const Vector3 &eye, const Vector3 &location, const Color &base);
 
-    /*!
+    /**
-     * \brief Alter a light, as if passed through all layers.
+     * Alter a light, as if passed through all layers.
      *
      * Return true if the light was altered.
      */

src/render/software/FluidMediumInterface.h

@@ -6,12 +6,12 @@
 namespace paysages {
 namespace software {
 
-/*!
+/**
- * \brief Interface to a fluid medium compatible class.
+ * Interface to a fluid medium compatible class.
  */
 class SOFTWARESHARED_EXPORT FluidMediumInterface {
   public:
-    /*!
+    /**
      * Return true if the object may change the fluid medium on the given segment.
      * When returning true, the object may alter 'segment' to limit its influence.
      */

src/render/software/FluidMediumManager.h

@@ -15,8 +15,8 @@ typedef struct {
     SpaceSegment segment;
 } FluidMediumSegment;
 
-/*!
+/**
- * \brief Global object to interact with fluid medium (air, water, clouds...)
+ * Global object to interact with fluid medium (air, water, clouds...)
  *
  * This object handles the traversal of fluid medium and the collecting of
  * medium density and properties.
@@ -27,27 +27,25 @@ class SOFTWARESHARED_EXPORT FluidMediumManager {
     FluidMediumManager(SoftwareRenderer *renderer);
     virtual ~FluidMediumManager();
 
-    /*!
+    /**
-     * \brief Remove all registered medium.
+     * Remove all registered medium.
      */
     void clearMedia();
 
-    /*!
+    /**
-     * \brief Register a new medium in the manager.
+     * Register a new medium in the manager.
      */
     void registerMedium(FluidMediumInterface *medium);
 
-    /*!
+    /**
-     * \brief Apply complete medium traversal
+     * Apply complete medium traversal between *location* and *eye*, to the base *color*.
-     * \param eye Position of the camera
+     *
-     * \param location Point we look at
+     * Returns the light received by eye, transformed by medium traversal.
-     * \param color Light initially received from 'location'
-     * \return Light received by 'eye', transformed by medium traversal
      */
     virtual Color applyTraversal(const Vector3 &eye, const Vector3 &location, const Color &color) const;
 
-    /*!
+    /**
-     * \brief Get the potential media traversed by a ray, unsorted
+     * Get the potential media traversed by a ray, unsorted
      */
     virtual int getTraversedMedia(FluidMediumSegment segments[], const SpaceSegment &ray, int max_segments) const;
 

src/render/software/LightComponent.h

@@ -10,7 +10,7 @@ namespace paysages {
 namespace software {
 
 /**
- * @brief One component of a LightStatus.
+ * One component of a LightStatus.
  *
  * A light component represents the amount of light received at a point from a given direction.
  */

src/render/software/LightFilter.h

@@ -7,12 +7,12 @@ namespace paysages {
 namespace software {
 
 /**
- * @brief Interface for rendering parts that can alter light.
+ * Interface for rendering parts that can alter light.
  */
 class SOFTWARESHARED_EXPORT LightFilter {
   public:
     /**
-     * @brief Apply filtering on a light component.
+     * Apply filtering on a light component.
      *
      * This will alter the component and return if the component is still
      * useful.

src/render/software/LightStatus.h

@@ -11,7 +11,7 @@ namespace paysages {
 namespace software {
 
 /**
- * @brief Light status at a given point.
+ * Light status at a given point.
  *
  * The light status is the combination of all LightComponent received at a given location.
  */

src/render/software/LightingManager.h

@@ -11,7 +11,7 @@ namespace paysages {
 namespace software {
 
 /**
- * @brief Global lighting manager.
+ * Global lighting manager.
  *
  * This manager handles the lights, light filters and final light rendering.
  *

src/render/software/NightSky.h

@@ -8,22 +8,23 @@
 namespace paysages {
 namespace software {
 
-/*!
+/**
- * \brief Night sky renderer.
+ * Night sky renderer.
  */
 class SOFTWARESHARED_EXPORT NightSky : public LightSource {
   public:
     NightSky(SoftwareRenderer *renderer);
     virtual ~NightSky();
 
-    /*!
+    /**
-     * \brief Update the night sky renderer, when the scenery or parent renderer changed.
+     * Update the night sky renderer, when the scenery or parent renderer changed.
      */
     void update();
 
-    /*!
+    /**
-     * \brief Get the color of the night sky at a given direction.
+     * Get the color of the night sky at a given direction.
-     * \param altitude Altitude above water level, in coordinate units (not kilometers).
+     *
+     * *altitude* is above water level, in coordinate units (not kilometers).
      */
     virtual const Color getColor(double altitude, const Vector3 &direction);
 

src/render/software/Rasterizer.h

@@ -15,7 +15,7 @@ typedef struct ScanPoint ScanPoint;
 typedef struct RenderScanlines RenderScanlines;
 
 /**
- * @brief Base abstract class for scenery pieces that can be rasterized to polygons.
+ * Base abstract class for scenery pieces that can be rasterized to polygons.
  */
 class SOFTWARESHARED_EXPORT Rasterizer {
   public:

src/render/software/SoftwareCanvasRenderer.h

@@ -12,7 +12,7 @@ namespace paysages {
 namespace software {
 
 /**
- * @brief Software rendering inside a Canvas surface.
+ * Software rendering inside a Canvas surface.
  *
  * This class launches the rasterization process into canvas portions and
  * redirects post processing to the software renderer.
@@ -70,19 +70,19 @@ class SOFTWARESHARED_EXPORT SoftwareCanvasRenderer : public SoftwareRenderer {
     void enablePostprocess(bool enabled);
 
     /**
-     * @brief Set the rendering size in pixels.
+     * Set the rendering size in pixels.
      *
      * Set 'samples' to something bigger than 1 to allow for the multi-sampling of pixels.
      */
     void setSize(int width, int height, int samples = 1);
 
     /**
-     * @brief Start the two-pass render process.
+     * Start the two-pass render process.
      */
     void render();
 
     /**
-     * @brief Interrupt the render process.
+     * Interrupt the render process.
      */
     void interrupt();
 
@@ -100,12 +100,12 @@ class SOFTWARESHARED_EXPORT SoftwareCanvasRenderer : public SoftwareRenderer {
 
   protected:
     /**
-     * @brief Rasterize the scenery into a canvas portion.
+     * Rasterize the scenery into a canvas portion.
      */
     void rasterize(CanvasPortion *portion);
 
     /**
-     * @brief Apply pixel shader to fragments stored in the CanvasPortion.
+     * Apply pixel shader to fragments stored in the CanvasPortion.
      */
     void applyPixelShader(CanvasPortion *portion);
 

src/render/software/SoftwareRenderer.h

@@ -6,8 +6,8 @@
 namespace paysages {
 namespace software {
 
-/*!
+/**
- * \brief This class renders a defined scenery in sotware mode (using only standard CPU computations).
+ * This class renders a defined scenery in sotware mode (using only standard CPU computations).
  */
 class SOFTWARESHARED_EXPORT SoftwareRenderer {
 
@@ -25,15 +25,15 @@ class SOFTWARESHARED_EXPORT SoftwareRenderer {
     virtual Vector3 projectPoint(const Vector3 &point);
     virtual Vector3 unprojectPoint(const Vector3 &point);
 
-    /*!
+    /**
-     * \brief Prepare the renderer sub-systems.
+     * Prepare the renderer sub-systems.
      *
      * This will clear the caches and connect elements together.
      * After this call, don't update the scenery when renderer is in use.
      */
     virtual void prepare();
 
-    /*!
+    /**
      * Set the global quality control factor.
      *
      * Values between 0.0 and 1.0 are standard quality (1.0 is considered a "very good" production quality value).

src/render/software/TerrainRasterizer.h

@@ -25,9 +25,9 @@ class SOFTWARESHARED_EXPORT TerrainRasterizer : public Rasterizer {
     /**
      * Set the rasterization quality.
      *
-     * @param base_chunk_size Size of chunks near the camera
+     * base_chunk_size - Size of chunks near the camera
-     * @param detail_factor Precision factor of a chunk's tessellation, depending on screen coverage
+     * detail_factor - Precision factor of a chunk's tessellation, depending on screen coverage
-     * @param max_chunk_detail Maximal tessellation of chunks
+     * max_chunk_detail - Maximal tessellation of chunks
      */
     void setQuality(double base_chunk_size, double detail_factor, int max_chunk_detail);
     virtual void setQuality(double factor) override;

src/render/software/TerrainRayWalker.h

@@ -8,8 +8,8 @@
 namespace paysages {
 namespace software {
 
-/*!
+/**
- * \brief Ray walker to find intersections with terrain.
+ * Ray walker to find intersections with terrain.
  *
  * This walker can be used to find a hard intersection between
  * a ray and the terrain (e.g. for raytracing), or a soft intersection
@@ -28,30 +28,31 @@ class SOFTWARESHARED_EXPORT TerrainRayWalker {
     /**
      * Set the walker quality.
      *
-     * @param displacement_safety Safety factor (around 1.0) to detect when displacement textures need to be applied
+     * displacement_safety - Safety factor (around 1.0) to detect when displacement textures need to be applied
-     * @param minimal_step Minimal length of a walking step
+     * minimal_step - Minimal length of a walking step
-     * @param maximal_step Maximal length of a walking step
+     * maximal_step - Maximal length of a walking step
-     * @param step_factor Precision factor of steps, depending on terrain proximity
+     * step_factor - Precision factor of steps, depending on terrain proximity
-     * @param max_distance Maximal distance allowed to travel before considering an escape
+     * max_distance - Maximal distance allowed to travel before considering an escape
-     * @param escape_step Angle step when allowing an escape angle
+     * escape_step - Angle step when allowing an escape angle
      */
     void setQuality(double displacement_safety, double minimal_step, double maximal_step, double step_factor,
                     double max_distance, double escape_step);
     void setQuality(double factor);
 
-    /*!
+    /**
-     * \brief Update the walker internal data, from the renderer and scenery.
+     * Update the walker internal data, from the renderer and scenery.
      */
     void update();
 
-    /*!
+    /**
-     * \brief Start the walking process to find intersection
+     * Start the walking process to find intersection
      *
-     * \param start Point of origin of the ray
+     * start - Point of origin of the ray
-     * \param direction Ray direction (normalized vector)
+     * direction - Ray direction (normalized vector)
-     * \param escape_angle Maximal angle allowed to escape the terrain on hit (mainly for shadows computing)
+     * escape_angle - Maximal angle allowed to escape the terrain on hit (mainly for shadows computing)
-     * \param result Object to store the results info
+     * result - Object to store the results info
-     * \return true if there was a hit
+     *
+     * Returns true if there was a hit.
      */
     bool startWalking(const Vector3 &start, Vector3 direction, double escape_angle, TerrainHitResult &result);
 

src/render/software/clouds/BaseCloudsModel.h

@@ -8,8 +8,8 @@
 namespace paysages {
 namespace software {
 
-/*!
+/**
- * \brief Abstract class for all cloud models (cirrus, cumulus...).
+ * Abstract class for all cloud models (cirrus, cumulus...).
  */
 class SOFTWARESHARED_EXPORT BaseCloudsModel {
   public:

src/system/Mutex.h

@@ -8,13 +8,13 @@
 namespace paysages {
 namespace system {
 
-/*!
+/**
- * \brief System mutex
+ * System mutex
  */
 class SYSTEMSHARED_EXPORT Mutex : private mutex {
   public:
-    /*!
+    /**
-     * \brief Create a new mutex
+     * Create a new mutex
      */
     Mutex();
 

src/system/PackStream.h

@@ -8,8 +8,8 @@
 namespace paysages {
 namespace system {
 
-/*!
+/**
- * \brief Data (de)serialization in files or streams.
+ * Data (de)serialization in files or streams.
  */
 class SYSTEMSHARED_EXPORT PackStream {
   public:

src/system/ParallelPool.h

@@ -8,7 +8,7 @@
 namespace paysages {
 namespace system {
 
-/*!
+/**
  * Pool to handle a group of threads doing the same task.
  */
 class SYSTEMSHARED_EXPORT ParallelPool {
@@ -16,17 +16,17 @@ class SYSTEMSHARED_EXPORT ParallelPool {
     ParallelPool();
     virtual ~ParallelPool();
 
-    /*!
+    /**
      * Start the effective work.
      */
     void start(int thread_count = -1);
 
-    /*!
+    /**
      * Method called from each thread to do actual work.
      */
     virtual void work() = 0;
 
-    /*!
+    /**
      * Method called once to interrupt all threads.
      */
     virtual void interrupt();

src/system/ParallelWork.h

@@ -43,7 +43,7 @@ class SYSTEMSHARED_EXPORT ParallelWork {
     /**
      * Start working on the units.
      *
-     * @param threads Number of threads to spaws, -1 for an optimal number.
+     * threads - Number of threads to spaws, -1 for an optimal number.
      */
     int perform(int thread_count = -1);
 

src/system/ParallelWorker.h

@@ -7,7 +7,7 @@ namespace paysages {
 namespace system {
 
 /**
- * @brief Worker that can be used by the ParallelWork object to perform tasks in several threads.
+ * Worker that can be used by the ParallelWork object to perform tasks in several threads.
  */
 class SYSTEMSHARED_EXPORT ParallelWorker {
   public:

src/system/PictureWriter.h

@@ -14,13 +14,13 @@ class SYSTEMSHARED_EXPORT PictureWriter {
     virtual ~PictureWriter();
 
     /**
-     * @brief Start saving the picture in a file.
+     * Start saving the picture in a file.
      */
     bool save(const string &filepath, int width, int height);
 
   protected:
     /**
-     * @brief Get the (x, y) pixel, in BGRA format
+     * Get the (x, y) pixel, in BGRA format
      */
     virtual unsigned int getPixel(int x, int y) = 0;
 };

src/system/System.h

@@ -6,8 +6,8 @@
 namespace paysages {
 namespace system {
 
-/*!
+/**
- * \brief Access to system info
+ * Access to system info
  */
 class SYSTEMSHARED_EXPORT System {
   public: