doxygen fixes

qgis · Apr 2, 2018 · fcacb0d · fcacb0d · nyalldawson · Apr 2, 2018
1 parent ca4bfb1
commit fcacb0d
Show file tree

Hide file tree

Showing 76 changed files with 319 additions and 252 deletions.
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -60,7 +60,7 @@ IF(WITH_APIDOC)
       ${CMAKE_SOURCE_DIR}/src/core/diagram
       ${CMAKE_SOURCE_DIR}/src/core/dxf
       ${CMAKE_SOURCE_DIR}/src/core/effects
-      ${CMAKE_SOURCE_DIR}/src/core/expressions
+      ${CMAKE_SOURCE_DIR}/src/core/expression
       ${CMAKE_SOURCE_DIR}/src/core/fieldformatter
       ${CMAKE_SOURCE_DIR}/src/core/geometry
       ${CMAKE_SOURCE_DIR}/src/core/geocms

diff --git a/python/core/expression/qgsexpression.sip.in b/python/core/expression/qgsexpression.sip.in
@@ -485,8 +485,6 @@ Returns the help text for a specified function.
 Returns the help text for a specified variable.
 
 :param variableName: name of variable
-:param showValue: set to true to include current value of variable in help text
-:param value: current value of variable to show in help text
 
 .. seealso:: :py:func:`helpText`
 

diff --git a/python/core/geometry/qgsgeometryutils.sip.in b/python/core/geometry/qgsgeometryutils.sip.in
@@ -147,12 +147,14 @@ supported and is retrieved from the first 3D point amongst ``p1`` and
  Compute the intersection of a line and a circle.
 If the intersection has two solutions (points),
 the closest point to the initial ``intersection`` point is returned.
-@param center the center of the circle
-@param radius the radius of the circle
-@param linePoint1 a first point on the line
-@param linePoint2 a second point on the line
-@param intersection the initial point and the returned intersection point
-@return true if an intersection has been found
+
+:param center: the center of the circle
+:param radius: the radius of the circle
+:param linePoint1: a first point on the line
+:param linePoint2: a second point on the line
+:param intersection: the initial point and the returned intersection point
+
+:return: true if an intersection has been found
 %End
 
     static int circleCircleIntersections( QgsPointXY center1, double radius1,

diff --git a/python/gui/editorwidgets/qgsdatetimeedit.sip.in b/python/gui/editorwidgets/qgsdatetimeedit.sip.in
@@ -77,7 +77,8 @@ Resets the widget to show no value (ie, an "unknown" state).
     void valueChanged( const QDateTime &date );
 %Docstring
 signal emitted whenever the value changes.
-@param date the new date/time value.
+
+:param date: the new date/time value.
 %End
 
   protected:

diff --git a/python/gui/qgsattributeeditorcontext.sip.in b/python/gui/qgsattributeeditorcontext.sip.in
@@ -48,16 +48,55 @@ Constructor for QgsAttributeEditorContext
     QgsAttributeEditorContext( const QgsAttributeEditorContext &parentContext, const QgsRelation &relation, RelationMode relationMode, FormMode widgetMode );
 
     void setDistanceArea( const QgsDistanceArea &distanceArea );
+%Docstring
+Sets distance area object for area/length calculations
+
+:param distanceArea: map canvas
+
+.. seealso:: :py:func:`setDistanceArea`
+
+.. versionadded:: 2.2
+%End
 
     const QgsDistanceArea &distanceArea() const;
 
     void setMapCanvas( QgsMapCanvas *mapCanvas );
+%Docstring
+Sets the map canvas (e.g. to zoom to related features)
+
+:param mapCanvas: map canvas
+
+.. seealso:: :py:func:`mapCanvas`
+
+.. versionadded:: 3.2
+%End
     QgsMapCanvas *mapCanvas() const;
 
     void setVectorLayerTools( QgsVectorLayerTools *vlTools );
+%Docstring
+Sets the vector layer tools
+
+:param vlTools: vector layer tools
+
+.. seealso:: :py:func:`vectorLayerTools`
+
+.. versionadded:: 2.2
+%End
     const QgsVectorLayerTools *vectorLayerTools() const;
 
     void setRelation( const QgsRelation &relation, RelationMode mode );
+%Docstring
+Set attribute relation and mode
+
+:param relation: relation
+:param mode: relation mode
+
+.. seealso:: :py:func:`relation`
+
+.. seealso:: :py:func:`relationMode`
+
+.. versionadded:: 2.6
+%End
     const QgsRelation &relation() const;
     RelationMode relationMode() const;
 

diff --git a/python/gui/qgsoptionsdialoghighlightwidget.sip.in b/python/gui/qgsoptionsdialoghighlightwidget.sip.in
@@ -29,7 +29,8 @@ This uses stylesheets.
 %Docstring
 create a highlight widget implementation for the proper widget type.
 For instance a QgsOptionsDialogHighlightButton for button.
-@return a QgsOptionsDialogHighlightWidget or a None if there is no implementation
+
+:return: a QgsOptionsDialogHighlightWidget or a None if there is no implementation
 for the given widget.
 %End
 

diff --git a/python/server/qgsserverprojectutils.sip.in b/python/server/qgsserverprojectutils.sip.in
@@ -355,7 +355,8 @@ Returns the WFS service url defined in a QGIS project.
 Returns the Layer ids list defined in a QGIS project as published in WFS.
 
 :param project: the QGIS project
-@return the Layer ids list.
+
+:return: the Layer ids list.
 %End
 
 
@@ -365,31 +366,35 @@ Returns the Layer precision defined in a QGIS project for the WFS GetFeature.
 
 :param project: the QGIS project
 :param layerId: the layer id in the project
-@return the layer precision for WFS GetFeature.
+
+:return: the layer precision for WFS GetFeature.
 %End
 
   QStringList wfstUpdateLayerIds( const QgsProject &project );
 %Docstring
 Returns the Layer ids list defined in a QGIS project as published as WFS-T with update capabilities.
 
 :param project: the QGIS project
-@return the Layer ids list.
+
+:return: the Layer ids list.
 %End
 
   QStringList wfstInsertLayerIds( const QgsProject &project );
 %Docstring
 Returns the Layer ids list defined in a QGIS project as published as WFS-T with insert capabilities.
 
 :param project: the QGIS project
-@return the Layer ids list.
+
+:return: the Layer ids list.
 %End
 
   QStringList wfstDeleteLayerIds( const QgsProject &project );
 %Docstring
 Returns the Layer ids list defined in a QGIS project as published as WFS-T with delete capabilities.
 
 :param project: the QGIS project
-@return the Layer ids list.
+
+:return: the Layer ids list.
 %End
 
   QString wcsServiceUrl( const QgsProject &project );

diff --git a/python/server/qgsserverrequest.sip.in b/python/server/qgsserverrequest.sip.in
@@ -94,7 +94,8 @@ Remove a parameter
 Return the header value
 
 :param name: of the header
-@return the header value or an empty string
+
+:return: the header value or an empty string
 %End
 
     void setHeader( const QString &name, const QString &value );
@@ -108,7 +109,8 @@ Set an header
     QMap<QString, QString> headers() const;
 %Docstring
 Return the header map
-@return the headers map
+
+:return: the headers map
 %End
 
     void removeHeader( const QString &name );

diff --git a/src/3d/terrain/quantizedmeshgeometry.cpp b/src/3d/terrain/quantizedmeshgeometry.cpp
@@ -26,10 +26,10 @@
 #define GZIP_CHUNK_SIZE 32 * 1024
 
 /**
- * @brief Decompresses the given buffer using the standard GZIP algorithm
- * @param input The buffer to be decompressed
- * @param output The result of the decompression
- * @return @c true if the decompression was successful, @c false otherwise
+ * \brief Decompresses the given buffer using the standard GZIP algorithm
+ * \param input The buffer to be decompressed
+ * \param output The result of the decompression
+ * \return \c true if the decompression was successful, \c false otherwise
  */
 bool gzipDecompress( QByteArray input, QByteArray &output )
 {

diff --git a/src/app/qgis-mime.ico b/src/app/qgis-mime.ico
diff --git a/src/app/qgisapp.cpp b/src/app/qgisapp.cpp
@@ -5965,7 +5965,7 @@ void QgisApp::openProject( const QString &fileName )
 /**
   Open a raster or vector file; ignore other files.
   Used to process a commandline argument or OpenDocument AppleEvent.
-  @returns true if the file is successfully opened
+  \returns true if the file is successfully opened
   */
 bool QgisApp::openLayer( const QString &fileName, bool allowInteractive )
 {
@@ -10536,7 +10536,7 @@ void QgisApp::setExtent( const QgsRectangle &rect )
 
 /**
   Prompt and save if project has been modified.
-  @return true if saved or discarded, false if canceled
+  \return true if saved or discarded, false if canceled
  */
 bool QgisApp::saveDirty()
 {

diff --git a/src/app/qgsdecorationnortharrow.cpp b/src/app/qgsdecorationnortharrow.cpp
@@ -52,8 +52,8 @@ const double QgsDecorationNorthArrow::TOL = 1e-8;
 /**
  * Constructor for the plugin. The plugin is passed a pointer to the main app
  * and an interface object that provides access to exposed functions in QGIS.
- * @param qgis Pointer to the QGIS main window
- * @param _qI Pointer to the QGIS interface object
+ * \param qgis Pointer to the QGIS main window
+ * \param _qI Pointer to the QGIS interface object
  */
 QgsDecorationNorthArrow::QgsDecorationNorthArrow( QObject *parent )
   : QgsDecorationItem( parent )

diff --git a/src/app/qgsversionmigration.h b/src/app/qgsversionmigration.h
@@ -37,13 +37,13 @@ class APP_EXPORT QgsVersionMigration
      * Check if two version has a migration options.
      * \param fromVersion The version migrating from.
      * \param toVersion The version migrating to.
-     * @return
+     * \returns migration object
      */
     static QgsVersionMigration *canMigrate( int fromVersion, int toVersion );
 
     /**
      * Run the version migration to convert between versions.
-     * @return QgsError containing any error messages when running the conversion.
+     * \return QgsError containing any error messages when running the conversion.
      */
     virtual QgsError runMigration() = 0;
     virtual bool requiresMigration() = 0;

diff --git a/src/core/expression/qgsexpression.h b/src/core/expression/qgsexpression.h
@@ -415,7 +415,7 @@ class CORE_EXPORT QgsExpression
 
     /**
      * Returns the number of functions defined in the parser
-     *  \returns The number of function defined in the parser.
+     * \returns The number of function defined in the parser.
      */
     static int functionCount();
 
@@ -467,8 +467,6 @@ class CORE_EXPORT QgsExpression
     /**
      * Returns the help text for a specified variable.
      * \param variableName name of variable
-     * \param showValue set to true to include current value of variable in help text
-     * \param value current value of variable to show in help text
      * \see helpText()
      * \since QGIS 2.12
      */

diff --git a/src/core/expression/qgsexpressionfunction.cpp b/src/core/expression/qgsexpressionfunction.cpp
@@ -216,11 +216,6 @@ bool QgsExpressionFunction::allParamsStatic( const QgsExpressionNodeFunction *no
   return true;
 }
 
-
-
-
-
-
 static QVariant fcnGetVariable( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction * )
 {
   if ( !context )

diff --git a/src/core/geometry/qgsgeometryutils.h b/src/core/geometry/qgsgeometryutils.h
@@ -140,15 +140,15 @@ class CORE_EXPORT QgsGeometryUtils
     static bool segmentIntersection( const QgsPoint &p1, const QgsPoint &p2, const QgsPoint &q1, const QgsPoint &q2, QgsPoint &intersectionPoint SIP_OUT, bool &isIntersection SIP_OUT, const double tolerance = 1e-8, bool acceptImproperIntersection = false );
 
     /**
-     * @brief Compute the intersection of a line and a circle.
+     * \brief Compute the intersection of a line and a circle.
      * If the intersection has two solutions (points),
      * the closest point to the initial \a intersection point is returned.
-     * @param center the center of the circle
-     * @param radius the radius of the circle
-     * @param linePoint1 a first point on the line
-     * @param linePoint2 a second point on the line
-     * @param intersection the initial point and the returned intersection point
-     * @return true if an intersection has been found
+     * \param center the center of the circle
+     * \param radius the radius of the circle
+     * \param linePoint1 a first point on the line
+     * \param linePoint2 a second point on the line
+     * \param intersection the initial point and the returned intersection point
+     * \return true if an intersection has been found
      */
     static bool lineCircleIntersection( const QgsPointXY &center, const double radius,
                                         const QgsPointXY &linePoint1, const QgsPointXY &linePoint2,

diff --git a/src/core/geometry/qgsgeos.h b/src/core/geometry/qgsgeos.h
@@ -229,7 +229,7 @@ class CORE_EXPORT QgsGeos: public QgsGeometryEngine
      * \param reshapeWithLine the line used to reshape lines or polygons
      * \param errorCode if specified, provides result of operation (success or reason of failure)
      * \param errorMsg if specified, provides more details about failure
-     * @return the reshaped geometry
+     * \return the reshaped geometry
      */
     std::unique_ptr< QgsAbstractGeometry > reshapeGeometry( const QgsLineString &reshapeWithLine, EngineOperationResult *errorCode, QString *errorMsg = nullptr ) const;
 

diff --git a/src/core/gps/qgsnmeaconnection.h b/src/core/gps/qgsnmeaconnection.h
@@ -32,7 +32,7 @@ class CORE_EXPORT QgsNmeaConnection: public QgsGpsConnection
   public:
 
     /**
-     * @brief Constructs a QgsNmeaConnection with given \a device.
+     * \brief Constructs a QgsNmeaConnection with given \a device.
      */
     QgsNmeaConnection( QIODevice *device );
 

diff --git a/src/core/pal/pal.h b/src/core/pal/pal.h
@@ -119,7 +119,7 @@ namespace pal
        *
        * \throws PalException::LayerExists
        *
-       * @todo add symbolUnit
+       * \todo add symbolUnit
        */
       Layer *addLayer( QgsAbstractLabelProvider *provider, const QString &layerName, QgsPalLayerSettings::Placement arrangement, double defaultPriority, bool active, bool toLabel, bool displayAll = false );
 

diff --git a/src/core/qgsproject.cpp b/src/core/qgsproject.cpp
@@ -113,11 +113,11 @@ QStringList makeKeyTokens_( const QString &scope, const QString &key )
 /**
    return the property that matches the given key sequence, if any
 
-   @param scope scope of key
-   @param key keyname
-   @param rootProperty is likely to be the top level QgsProjectPropertyKey in QgsProject:e:Imp.
+   \param scope scope of key
+   \param key keyname
+   \param rootProperty is likely to be the top level QgsProjectPropertyKey in QgsProject:e:Imp.
 
-   @return null if not found, otherwise located Property
+   \return null if not found, otherwise located Property
 */
 QgsProjectProperty *findKey_( const QString &scope,
                               const QString &key,
@@ -190,10 +190,10 @@ QgsProjectProperty *findKey_( const QString &scope,
 /**
  * Add the given key and value
 
-@param scope scope of key
-@param key key name
-@param rootProperty is the property from which to start adding
-@param value the value associated with the key
+\param scope scope of key
+\param key key name
+\param rootProperty is the property from which to start adding
+\param value the value associated with the key
 */
 QgsProjectProperty *addKey_( const QString &scope,
                              const QString &key,
@@ -590,8 +590,8 @@ scope.  "layers" is a list containing three string values.
 </properties>
 \endcode
 
-@param doc xml document
-@param project_properties should be the top QgsProjectPropertyKey node.
+\param doc xml document
+\param project_properties should be the top QgsProjectPropertyKey node.
 
 */
 void _getProperties( const QDomDocument &doc, QgsProjectPropertyKey &project_properties )
@@ -620,7 +620,7 @@ void _getProperties( const QDomDocument &doc, QgsProjectPropertyKey &project_pro
 
 /**
    Get the project title
-   @todo XXX we should go with the attribute xor title, not both.
+   \todo XXX we should go with the attribute xor title, not both.
 */
 static void _getTitle( const QDomDocument &doc, QString &title )
 {

diff --git a/src/core/qgsvectorlayer.h b/src/core/qgsvectorlayer.h
@@ -2284,7 +2284,7 @@ class CORE_EXPORT QgsVectorLayer : public QgsMapLayer, public QgsExpressionConte
     /**
      * Bind layer to a specific data provider
      * \param provider should be "postgres", "ogr", or ??
-     * @todo XXX should this return bool?  Throw exceptions?
+     * \todo XXX should this return bool?  Throw exceptions?
      */
     bool setDataProvider( QString const &provider );
 

diff --git a/src/core/qgsvectorlayerundopassthroughcommand.cpp b/src/core/qgsvectorlayerundopassthroughcommand.cpp
@@ -26,7 +26,7 @@
 
 #include <QUuid>
 
-//@todo use setObsolete instead of mHasError when upgrading qt version, this will allow auto removal of the command
+//\todo use setObsolete instead of mHasError when upgrading qt version, this will allow auto removal of the command
 // for the moment a errored command is left on the stack
 
 QgsVectorLayerUndoPassthroughCommand::QgsVectorLayerUndoPassthroughCommand( QgsVectorLayerEditBuffer *buffer, const QString &text, bool autocreate )