Add more consistency to doxygen formatting

qgis · Oct 5, 2017 · 04a9cd9 · 04a9cd9
1 parent 78c0c28
commit 04a9cd9
Show file tree

Hide file tree

Showing 1,027 changed files with 12,159 additions and 6,076 deletions.
diff --git a/scripts/doxygen_space.pl b/scripts/doxygen_space.pl
@@ -72,13 +72,24 @@
        }
     }
     else {
-        if ( !$PREVIOUS_WAS_BLANKLINE && $new_line =~ m/^(\s*)\/\*\*\s/ ){
+        if ( $new_line =~ m/^(\s*)\/\*\*(?!\*)\s*(.*)$/ ){
           # Space around doxygen start blocks (force blank line before /**)
-          print $out_handle "\n";
+          if ( !$PREVIOUS_WAS_BLANKLINE ){
+              print $out_handle "\n";
+          }
+          if ( $2 ne '' ){
+              # new line after /** begin block
+              print $out_handle "$1\/**\n$1 * $2\n";
+          }
+          else {
+              print $out_handle $new_line."\n";
+          }
+        }
+        else {
+            print $out_handle $new_line."\n";
         }
-        print $out_handle $new_line."\n";
     }
     $LINE_IDX++;
     $PREVIOUS_WAS_BLANKLINE = $is_blank_line;
 }
-close $out_handle;
+close $out_handle;
diff --git a/src/3d/chunks/qgschunkboundsentity_p.h b/src/3d/chunks/qgschunkboundsentity_p.h
@@ -33,7 +33,8 @@ class QgsAABB;
 class AABBMesh;
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Draws bounds of axis aligned bounding boxes
  * \since QGIS 3.0
  */

diff --git a/src/3d/chunks/qgschunkedentity_p.h b/src/3d/chunks/qgschunkedentity_p.h
@@ -42,7 +42,8 @@ class QgsChunkQueueJobFactory;
 
 #include <QTime>
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Implementation of entity that handles chunks of data organized in quadtree with loading data when necessary
  * based on data error and unloading of data when data are not necessary anymore
  * \since QGIS 3.0

diff --git a/src/3d/chunks/qgschunklist_p.h b/src/3d/chunks/qgschunklist_p.h
@@ -29,7 +29,8 @@
 
 class QgsChunkNode;
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Element of a double-linked list
  * \since QGIS 3.0
  */
@@ -47,7 +48,8 @@ struct QgsChunkListEntry
 };
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Double linked list of chunks.
  * The list does not own entries.
  *

diff --git a/src/3d/chunks/qgschunkloader_p.h b/src/3d/chunks/qgschunkloader_p.h
@@ -29,7 +29,8 @@
 
 #include "qgschunkqueuejob_p.h"
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Base class for jobs that load chunks
  * \since QGIS 3.0
  */
@@ -54,7 +55,8 @@ class QgsChunkLoader : public QgsChunkQueueJob
 };
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Factory for chunk loaders for a particular type of entity
  * \since QGIS 3.0
  */

diff --git a/src/3d/chunks/qgschunknode_p.h b/src/3d/chunks/qgschunknode_p.h
@@ -42,7 +42,8 @@ class QgsChunkQueueJob;
 class QgsChunkQueueJobFactory;
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Data structure for keeping track of chunks of data for 3D entities that use "out of core" rendering,
  * i.e. not all of the data are available in the memory all the time. This is useful for large datasets
  * where it may be impossible to load all data into memory or the rendering would get very slow.

diff --git a/src/3d/chunks/qgschunkqueuejob_p.h b/src/3d/chunks/qgschunkqueuejob_p.h
@@ -36,7 +36,8 @@ namespace Qt3DCore
 
 #include <QObject>
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Base class for chunk queue jobs. Job implementations start their work when they are created
  * and all work is done asynchronously, i.e. constructor should exit as soon as possible and
  * all work should be done in a worker thread. Once the job is done, finished() signal is emitted
@@ -76,7 +77,8 @@ class QgsChunkQueueJob : public QObject
     QgsChunkNode *mNode = nullptr;
 };
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Base class for factories of chunk queue jobs. Derived classes need to implement createJob()
  * method that will create a specific job for given chunk node.
  * \since QGIS 3.0

diff --git a/src/3d/qgs3dmapscene.h b/src/3d/qgs3dmapscene.h
@@ -42,7 +42,8 @@ class Qgs3DMapSettings;
 class QgsTerrainEntity;
 class QgsChunkedEntity;
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Entity that encapsulates our 3D scene - contains all other entities (such as terrain) as children.
  * \since QGIS 3.0
  */

diff --git a/src/3d/qgs3dmapsettings.h b/src/3d/qgs3dmapsettings.h
@@ -37,7 +37,8 @@ class QgsProject;
 
 class QDomElement;
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Definition of the world
  *
  * \since QGIS 3.0

diff --git a/src/3d/qgs3dutils.h b/src/3d/qgs3dutils.h
@@ -39,7 +39,8 @@ enum AltitudeBinding
 };
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Miscellaneous utility functions used from 3D code.
  * \since QGIS 3.0
  */

diff --git a/src/3d/qgsaabb.h b/src/3d/qgsaabb.h
@@ -22,7 +22,8 @@
 #include <QList>
 #include <QVector3D>
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Axis-aligned bounding box - in world coords.
  * \since QGIS 3.0
  */

diff --git a/src/3d/qgscameracontroller.h b/src/3d/qgscameracontroller.h
@@ -23,7 +23,8 @@
 #include <Qt3DRender>
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Object that controls camera movement based on user input
  * \since QGIS 3.0
  */

diff --git a/src/3d/qgsphongmaterialsettings.h b/src/3d/qgsphongmaterialsettings.h
@@ -22,7 +22,8 @@
 
 class QDomElement;
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Basic shading material used for rendering based on the Phong shading model
  * with three color components: ambient, diffuse and specular.
  * \since QGIS 3.0

diff --git a/src/3d/qgstessellatedpolygongeometry.h b/src/3d/qgstessellatedpolygongeometry.h
@@ -25,7 +25,8 @@ namespace Qt3DRender
   class QBuffer;
 }
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Class derived from Qt3DRender::QGeometry that represents polygons tessellated into 3D geometry.
  *
  * Takes a list of polygons as input, internally it does tessellation and writes output to the internal

diff --git a/src/3d/qgstessellator.h b/src/3d/qgstessellator.h
@@ -21,7 +21,8 @@ class QgsPolygonV2;
 #include <QVector>
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Class that takes care of tessellation of polygons into triangles.
  *
  * It is expected that client code will create the tessellator object, then repeatedly call

diff --git a/src/3d/qgstilingscheme.h b/src/3d/qgstilingscheme.h
@@ -23,7 +23,8 @@
 
 class QgsRectangle;
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * The class encapsulates tiling scheme (just like with WMTS / TMS / XYZ layers).
  * The origin (tile [0,0]) is in bottom-left corner.
  * \since QGIS 3.0

diff --git a/src/3d/qgsvectorlayer3drenderer.h b/src/3d/qgsvectorlayer3drenderer.h
@@ -33,7 +33,8 @@ class QgsVectorLayer;
 class QgsAbstract3DSymbol;
 
 
-/** \ingroup core
+/**
+ * \ingroup core
  * Metadata for vector layer 3D renderer to allow creation of its instances from XML
  * \since QGIS 3.0
  */
@@ -47,7 +48,8 @@ class _3D_EXPORT QgsVectorLayer3DRendererMetadata : public Qgs3DRendererAbstract
 };
 
 
-/** \ingroup core
+/**
+ * \ingroup core
  * 3D renderer that renders all features of a vector layer with the same 3D symbol.
  * The appearance is completely defined by the symbol.
  * \since QGIS 3.0

diff --git a/src/3d/symbols/qgsline3dsymbol.h b/src/3d/symbols/qgsline3dsymbol.h
@@ -23,7 +23,8 @@
 #include "qgs3dutils.h"
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * 3D symbol that draws linestring geometries as planar polygons (created from lines using a buffer with given thickness).
  * \since QGIS 3.0
  */

diff --git a/src/3d/symbols/qgspoint3dsymbol.h b/src/3d/symbols/qgspoint3dsymbol.h
@@ -23,7 +23,8 @@
 #include "qgs3dutils.h"
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * 3D symbol that draws point geometries as 3D objects using one of the predefined shapes.
  *
  * \since QGIS 3.0

diff --git a/src/3d/symbols/qgspolygon3dsymbol.h b/src/3d/symbols/qgspolygon3dsymbol.h
@@ -23,7 +23,8 @@
 #include "qgs3dutils.h"
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * 3D symbol that draws polygon geometries as planar polygons, optionally extruded (with added walls).
  * \since QGIS 3.0
  */

diff --git a/src/3d/terrain/qgsdemterraingenerator.h b/src/3d/terrain/qgsdemterraingenerator.h
@@ -28,7 +28,8 @@ class QgsRasterLayer;
 
 #include "qgsmaplayerref.h"
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Implementation of terrain generator that uses a raster layer with DEM to build terrain.
  * \since QGIS 3.0
  */

diff --git a/src/3d/terrain/qgsdemterraintilegeometry_p.h b/src/3d/terrain/qgsdemterraintilegeometry_p.h
@@ -42,7 +42,8 @@ namespace Qt3DRender
 } // Qt3DRender
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Stores attributes and vertex/index buffers for one terrain tile based on DEM.
  * \since QGIS 3.0
  */

diff --git a/src/3d/terrain/qgsdemterraintileloader_p.h b/src/3d/terrain/qgsdemterraintileloader_p.h
@@ -38,7 +38,8 @@
 class QgsRasterDataProvider;
 class QgsRasterLayer;
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Chunk loader for DEM terrain tiles.
  * \since QGIS 3.0
  */
@@ -64,7 +65,8 @@ class QgsDemTerrainTileLoader : public QgsTerrainTileLoader
 
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Utility class to asynchronously create heightmaps from DEM raster for given tiles of terrain.
  * \since QGIS 3.0
  */

diff --git a/src/3d/terrain/qgsflatterraingenerator.h b/src/3d/terrain/qgsflatterraingenerator.h
@@ -23,7 +23,8 @@
 #include "qgsrectangle.h"
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Terrain generator that creates a simple square flat area.
  *
  * \since QGIS 3.0

diff --git a/src/3d/terrain/qgsterrainentity_p.h b/src/3d/terrain/qgsterrainentity_p.h
@@ -44,7 +44,8 @@ class QgsMapLayer;
 class QgsTerrainGenerator;
 class TerrainMapUpdateJobFactory;
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Controller for terrain - decides on what terrain tiles to show based on camera position
  * and creates them using map's terrain tile generator.
  * \since QGIS 3.0

diff --git a/src/3d/terrain/qgsterraingenerator.h b/src/3d/terrain/qgsterraingenerator.h
@@ -31,7 +31,8 @@ class QDomDocument;
 class QgsProject;
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Base class for generators of terrain. All terrain generators are tile based
  * to support hierarchical level of detail. Tiling scheme of a generator is defined
  * by the generator itself. Terrain generators are asked to produce new terrain tiles

diff --git a/src/3d/terrain/qgsterraintexturegenerator_p.h b/src/3d/terrain/qgsterraintexturegenerator_p.h
@@ -38,7 +38,8 @@ class QgsRasterLayer;
 
 class Qgs3DMapSettings;
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Class responsible for rendering map images in background for the purposes of their use
  * as textures for terrain's tiles.
  *

diff --git a/src/3d/terrain/qgsterraintextureimage_p.h b/src/3d/terrain/qgsterraintextureimage_p.h
@@ -33,7 +33,8 @@
 
 class QgsTerrainTextureGenerator;
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Class that stores an image with a rendered map. The image is used as a texture for one map tile.
  *
  * The texture is provided to Qt 3D through the implementation of dataGenerator() method.

diff --git a/src/3d/terrain/qgsterraintileentity_p.h b/src/3d/terrain/qgsterraintileentity_p.h
@@ -31,7 +31,8 @@ class QgsTerrainTextureImage;
 
 #include <Qt3DCore/QEntity>
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Base class for 3D entities representing one tile of terrain.
  * It contains pointer to tile's texture image.
  *

diff --git a/src/3d/terrain/qgsterraintileloader_p.h b/src/3d/terrain/qgsterraintileloader_p.h
@@ -36,7 +36,8 @@ class QgsTerrainEntity;
 class QgsTerrainTileEntity;
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Base class for chunk loaders for terrain tiles.
  * Adds functionality for asynchronous rendering of terrain tile map texture and access to the terrain entity.
  * \since QGIS 3.0

diff --git a/src/3d/terrain/quantizedmeshgeometry.h b/src/3d/terrain/quantizedmeshgeometry.h
@@ -54,7 +54,8 @@ class QgsMapToPixel;
 
 class Map3D;
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Stores vertex and index buffer for one tile of quantized mesh terrain.
  * \since QGIS 3.0
  */

diff --git a/src/3d/terrain/quantizedmeshterraingenerator.h b/src/3d/terrain/quantizedmeshterraingenerator.h
@@ -4,7 +4,8 @@
 #include "qgsterraingenerator.h"
 
 
-/** \ingroup 3d
+/**
+ * \ingroup 3d
  * Terrain generator using downloaded terrain tiles using quantized mesh specification
  * \since QGIS 3.0
  */

diff --git a/src/analysis/interpolation/Bezier3D.h b/src/analysis/interpolation/Bezier3D.h
@@ -23,7 +23,8 @@
 
 #define SIP_NO_FILE
 
-/** \ingroup analysis
+/**
+ * \ingroup analysis
  * Class Bezier3D represents a bezier curve, represented by control points. Parameter t is running from 0 to 1. The class is capable to calculate the curve point and the first two derivatives belonging to it.
  * \note Not available in Python bindings
 */