Followup fcacb0d, fix doxygen tests

Also: - move doxygen comments to header files so that they get included in Python docstrings - remove duplicate doxygen implemented in both header and footer - remove some redundant doxygen for overridden methods - add some missing docs
qgis · Apr 2, 2018 · 1bf1058 · 1bf1058
1 parent fcacb0d
commit 1bf1058
Show file tree

Hide file tree

Showing 49 changed files with 754 additions and 517 deletions.
diff --git a/python/core/expression/qgsexpressionfunction.sip.in b/python/core/expression/qgsexpressionfunction.sip.in
@@ -247,10 +247,18 @@ Returns result of evaluating the function.
 %End
 
     virtual QVariant run( QgsExpressionNode::NodeList *args, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node );
+%Docstring
+Evaluates the function, first evaluating all required arguments before passing them to the
+function's func() method.
+%End
 
     bool operator==( const QgsExpressionFunction &other ) const;
 
     virtual bool handlesNull() const;
+%Docstring
+Returns true if the function handles NULL values in arguments by itself, and the default
+NULL value handling should be skipped.
+%End
 
   protected:
 

diff --git a/python/core/expression/qgsexpressionnode.sip.in b/python/core/expression/qgsexpressionnode.sip.in
@@ -51,6 +51,7 @@ Abstract base class for all nodes that can appear in an expression.
     }
 %End
   public:
+
     enum NodeType
     {
       ntUnaryOperator,
@@ -82,6 +83,9 @@ Constructor for NamedNode
 
     class NodeList
 {
+%Docstring
+A list of expression nodes.
+%End
 
 %TypeHeaderCode
 #include "qgsexpressionnode.h"
@@ -137,6 +141,9 @@ Creates a deep copy of this list. Ownership is transferred to the caller
 %End
 
         virtual QString dump() const;
+%Docstring
+Returns a string dump of the expression node.
+%End
 
       public:
     };

diff --git a/python/core/expression/qgsexpressionnodeimpl.sip.in b/python/core/expression/qgsexpressionnodeimpl.sip.in
@@ -33,7 +33,14 @@ A node unary operator is modifying the value of ``operand`` by negating it with
     ~QgsExpressionNodeUnaryOperator();
 
     QgsExpressionNodeUnaryOperator::UnaryOperator op() const;
+%Docstring
+Returns the unary operator.
+%End
+
     QgsExpressionNode *operand() const;
+%Docstring
+Returns the node the operator will operate upon.
+%End
 
     virtual QgsExpressionNode::NodeType nodeType() const;
 
@@ -66,6 +73,9 @@ I.e. "NOT" or "-"
 
 class QgsExpressionNodeBinaryOperator : QgsExpressionNode
 {
+%Docstring
+A binary expression operator, which operates on two values.
+%End
 
 %TypeHeaderCode
 #include "qgsexpressionnodeimpl.h"
@@ -113,8 +123,23 @@ Binary combination of the left and the right with op.
     ~QgsExpressionNodeBinaryOperator();
 
     QgsExpressionNodeBinaryOperator::BinaryOperator op() const;
+%Docstring
+Returns the binary operator.
+%End
+
     QgsExpressionNode *opLeft() const;
+%Docstring
+Returns the node to the left of the operator.
+
+.. seealso:: :py:func:`opRight`
+%End
+
     QgsExpressionNode *opRight() const;
+%Docstring
+Returns the node to the right of the operator.
+
+.. seealso:: :py:func:`opLeft`
+%End
 
     virtual QgsExpressionNode::NodeType nodeType() const;
 
@@ -137,7 +162,14 @@ Binary combination of the left and the right with op.
 
 
     int precedence() const;
+%Docstring
+Returns the precedence index for the operator. Higher values have higher precedence.
+%End
+
     bool leftAssociative() const;
+%Docstring
+Returns true if the operator is left-associative.
+%End
 
     QString text() const;
 %Docstring
@@ -149,6 +181,9 @@ I.e. "AND", "OR", ...
 
 class QgsExpressionNodeInOperator : QgsExpressionNode
 {
+%Docstring
+An expression node for value IN or NOT IN clauses.
+%End
 
 %TypeHeaderCode
 #include "qgsexpressionnodeimpl.h"
@@ -162,8 +197,19 @@ This node tests if the result of ``node`` is in the result of ``list``. Optional
     ~QgsExpressionNodeInOperator();
 
     QgsExpressionNode *node() const;
+%Docstring
+Returns the expression node.
+%End
+
     bool isNotIn() const;
+%Docstring
+Returns true if this node is a "NOT IN" operator, or false if the node is a normal "IN" operator.
+%End
+
     QgsExpressionNode::NodeList *list() const;
+%Docstring
+Returns the list of nodes to search for matching values within.
+%End
 
     virtual QgsExpressionNode::NodeType nodeType() const;
 
@@ -189,6 +235,9 @@ This node tests if the result of ``node`` is in the result of ``list``. Optional
 
 class QgsExpressionNodeFunction : QgsExpressionNode
 {
+%Docstring
+An expression node for expression functions.
+%End
 
 %TypeHeaderCode
 #include "qgsexpressionnodeimpl.h"
@@ -204,7 +253,14 @@ a list of arguments that will be passed to it.
     ~QgsExpressionNodeFunction();
 
     int fnIndex() const;
+%Docstring
+Returns the index of the node's function.
+%End
+
     QgsExpressionNode::NodeList *args() const;
+%Docstring
+Returns a list of arguments specified for the function.
+%End
 
     virtual QgsExpressionNode::NodeType nodeType() const;
 
@@ -235,12 +291,19 @@ Tests whether the provided argument list is valid for the matching function
 
 class QgsExpressionNodeLiteral : QgsExpressionNode
 {
+%Docstring
+An expression node for literal values.
+%End
 
 %TypeHeaderCode
 #include "qgsexpressionnodeimpl.h"
 %End
   public:
+
     QgsExpressionNodeLiteral( const QVariant &value );
+%Docstring
+Constructor for QgsExpressionNodeLiteral, with the specified literal ``value``.
+%End
 
     QVariant value() const;
 %Docstring
@@ -271,12 +334,20 @@ The value of the literal.
 
 class QgsExpressionNodeColumnRef : QgsExpressionNode
 {
+%Docstring
+An expression node which takes it value from a feature's field.
+%End
 
 %TypeHeaderCode
 #include "qgsexpressionnodeimpl.h"
 %End
   public:
+
     QgsExpressionNodeColumnRef( const QString &name );
+%Docstring
+Constructor for QgsExpressionNodeColumnRef, referencing the column
+with the specified ``name``.
+%End
 
     QString name() const;
 %Docstring
@@ -308,13 +379,20 @@ The name of the column.
 
 class QgsExpressionNodeCondition : QgsExpressionNode
 {
+%Docstring
+An expression node for CASE WHEN clauses.
+%End
 
 %TypeHeaderCode
 #include "qgsexpressionnodeimpl.h"
 %End
   public:
+
     class WhenThen
 {
+%Docstring
+Represents a "WHEN... THEN..." portation of a CASE WHEN clause in an expression.
+%End
 
 %TypeHeaderCode
 #include "qgsexpressionnodeimpl.h"

diff --git a/python/core/qgssqlstatement.sip.in b/python/core/qgssqlstatement.sip.in
@@ -250,7 +250,7 @@ v.visit( self)
     class NodeList
 {
 %Docstring
-List of nodes *
+A list of nodes.
 %End
 
 %TypeHeaderCode

diff --git a/python/core/raster/qgscontrastenhancement.sip.in b/python/core/raster/qgscontrastenhancement.sip.in
@@ -38,24 +38,25 @@ ContrastEnhancementAlgorithm.
     ~QgsContrastEnhancement();
 
 
+
     static double maximumValuePossible( Qgis::DataType );
 %Docstring
- Helper function that returns the maximum possible value for a GDAL data type
+Helper function that returns the maximum possible value for a GDAL data type.
 %End
 
     static double minimumValuePossible( Qgis::DataType );
 %Docstring
- Helper function that returns the minimum possible value for a GDAL data type
+Helper function that returns the minimum possible value for a GDAL data type.
 %End
 
     static QString contrastEnhancementAlgorithmString( ContrastEnhancementAlgorithm algorithm );
 %Docstring
- Return a string to serialize ContrastEnhancementAlgorithm
+Return a string to serialize ContrastEnhancementAlgorithm.
 %End
 
     static ContrastEnhancementAlgorithm contrastEnhancementAlgorithmFromString( const QString &contrastEnhancementString );
 %Docstring
- Deserialize ContrastEnhancementAlgorithm
+Deserialize ContrastEnhancementAlgorithm.
 %End
 
     double maximumValue() const;
@@ -70,34 +71,55 @@ ContrastEnhancementAlgorithm.
 
     ContrastEnhancementAlgorithm contrastEnhancementAlgorithm() const;
 
-    int enhanceContrast( double );
+
+    int enhanceContrast( double value );
 %Docstring
- Apply the contrast enhancement to a value. Return values are 0 - 254, -1 means the pixel was clipped and should not be displayed
+Applies the contrast enhancement to a ``value``. Return values are 0 - 254, -1 means the pixel was clipped and should not be displayed.
 %End
 
-    bool isValueInDisplayableRange( double );
+    bool isValueInDisplayableRange( double value );
 %Docstring
- Return true if pixel is in stretable range, false if pixel is outside of range (i.e., clipped)
+Return true if a pixel ``value`` is in displayable range, false if pixel
+is outside of range (i.e. clipped).
 %End
 
-    void setContrastEnhancementAlgorithm( ContrastEnhancementAlgorithm, bool generateTable = true );
+    void setContrastEnhancementAlgorithm( ContrastEnhancementAlgorithm algorithm, bool generateTable = true );
 %Docstring
- Set the contrast enhancement algorithm
+Sets the contrast enhancement ``algorithm``.
+
+The ``generateTable`` parameter is optional and is for performance improvements.
+If you know you are immediately going to set the Minimum or Maximum value, you
+can elect to not generate the lookup tale. By default it will be generated.
 %End
 
-    void setContrastEnhancementFunction( QgsContrastEnhancementFunction * );
+    void setContrastEnhancementFunction( QgsContrastEnhancementFunction *function /Transfer/ );
 %Docstring
- A public method that allows the user to set their own custom contrast enhancement function
+Allows the user to set their own custom contrast enhancement ``function``. Ownership of
+``function`` is transfered.
 %End
 
-    void setMaximumValue( double, bool generateTable = true );
+    void setMaximumValue( double value, bool generateTable = true );
 %Docstring
- Set the maximum value for the contrast enhancement range.
+Sets the maximum ``value`` for the contrast enhancement range.
+
+The ``generateTable`` parameter is optional and is for performance improvements.
+If you know you are immediately going to set the minimum value or the contrast
+enhancement algorithm, you can elect to not generate the lookup table.
+By default it will be generated.
+
+.. seealso:: :py:func:`setMinimumValue`
 %End
 
-    void setMinimumValue( double, bool generateTable = true );
+    void setMinimumValue( double value, bool generateTable = true );
 %Docstring
- Return the minimum value for the contrast enhancement range.
+Sets the minimum ``value`` for the contrast enhancement range.
+
+The ``generateTable`` parameter is optional and is for performance improvements.
+If you know you are immediately going to set the maximum value or the contrast
+enhancement algorithm, you can elect to not generate the lookup table.
+By default it will be generated.
+
+.. seealso:: :py:func:`setMaximumValue`
 %End
 
     void writeXml( QDomDocument &doc, QDomElement &parentElem ) const;