diff --git a/python/core/expression/qgsexpressionfunction.sip.in b/python/core/expression/qgsexpressionfunction.sip.in index 530a8726aa98..d3773739d5ba 100644 --- 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 index 039f2e1c7347..634242feb75b 100644 --- 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 index a5f707d93315..9c3c01c59117 100644 --- 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 index 500afcab4b8a..f069f3d3da89 100644 --- 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 index beebdaf00e74..6c136d40ebb2 100644 --- 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; diff --git a/python/core/raster/qgsrasterlayer.sip.in b/python/core/raster/qgsrasterlayer.sip.in index 93f4ea493036..456a2d90ab64 100644 --- a/python/core/raster/qgsrasterlayer.sip.in +++ b/python/core/raster/qgsrasterlayer.sip.in @@ -170,8 +170,9 @@ created for the same data source and renderer is cloned too. This helper checks to see whether the file name appears to be a valid raster file name. If the file name looks like it could be valid, but some sort of error occurs in processing the file, the error is -returned in retError. +returned in ``retError``. %End + static bool isValidRasterFileName( const QString &fileNameQString ); static QDateTime lastModified( const QString &name ); @@ -233,27 +234,11 @@ Get raster pipe virtual const QgsRasterDataProvider *dataProvider() const /PyName=constDataProvider/; -%Docstring -Returns the data provider in a const-correct manner - -.. note:: - - available in Python bindings as constDataProvider() -%End virtual void reload(); -%Docstring -Synchronises with changes in the datasource -%End - virtual QgsMapLayerRenderer *createMapRenderer( QgsRenderContext &rendererContext ) /Factory/; -%Docstring -Return new instance of QgsMapLayerRenderer that will be used for rendering of given context - -.. versionadded:: 2.4 -%End void draw( QPainter *theQPainter, QgsRasterViewPort *myRasterViewPort, @@ -274,7 +259,9 @@ Returns a list with classification items (Text and color) QPixmap paletteAsPixmap( int bandNumber = 1 ); %Docstring - Get an 100x100 pixmap of the color palette. If the layer has no palette a white pixmap will be returned +Returns a 100x100 pixmap of the color palette. If the layer has no palette a white pixmap will be returned + +:param bandNumber: the number of the band to use for generating a pixmap of the associated palette %End QString providerType() const; @@ -284,11 +271,21 @@ Returns a list with classification items (Text and color) double rasterUnitsPerPixelX() const; %Docstring - Returns the number of raster units per each raster pixel in X axis. In a world file, this is normally the first row (without the sign) +Returns the number of raster units per each raster pixel in X axis. + +In a world file, this is normally the first row (without the sign). (E.g. +the value reported by the GDAL geotransform[1]). + +.. seealso:: :py:func:`rasterUnitsPerPixelY` %End + double rasterUnitsPerPixelY() const; %Docstring - Returns the number of raster units per each raster pixel in Y axis. In a world file, this is normally the first row (without the sign) +Returns the number of raster units per each raster pixel in Y axis. + +In a world file, this is normally the first row (without the sign). + +.. seealso:: :py:func:`rasterUnitsPerPixelX` %End @@ -318,9 +315,6 @@ Returns a list with classification items (Text and color) virtual QStringList subLayers() const; -%Docstring - Returns the sublayers of this layer - Useful for providers that manage their own layers, such as WMS -%End QImage previewAsImage( QSize size, const QColor &bgColor = Qt::white, QImage::Format format = QImage::Format_ARGB32_Premultiplied ); @@ -332,23 +326,10 @@ Returns a list with classification items (Text and color) virtual void setLayerOrder( const QStringList &layers ); -%Docstring -Reorders the *previously selected* sublayers of this layer from bottom to top - -(Useful for providers that manage their own layers, such as WMS) -%End - virtual void setSubLayerVisibility( const QString &name, bool vis ); -%Docstring -Set the visibility of the given sublayer name -%End - virtual QDateTime timestamp() const; -%Docstring -Time stamp of data source in the moment when data/metadata were loaded by provider -%End public slots: void showStatusMessage( const QString &message ); @@ -356,39 +337,16 @@ Time stamp of data source in the moment when data/metadata were loaded by provid protected: virtual bool readSymbology( const QDomNode &node, QString &errorMessage, QgsReadWriteContext &context ); -%Docstring - Read the symbology for the current layer from the Dom node supplied -%End - virtual bool readStyle( const QDomNode &node, QString &errorMessage, QgsReadWriteContext &context ); -%Docstring - Read the style information for the current layer from the Dom node supplied -%End - virtual bool readXml( const QDomNode &layer_node, QgsReadWriteContext &context ); -%Docstring - Reads layer specific state from project file Dom node -%End - virtual bool writeSymbology( QDomNode &, QDomDocument &doc, QString &errorMessage, const QgsReadWriteContext &context ) const; -%Docstring - Write the symbology for the layer into the docment provided -%End - virtual bool writeStyle( QDomNode &node, QDomDocument &doc, QString &errorMessage, const QgsReadWriteContext &context ) const; -%Docstring - Write the style for the layer into the docment provided -%End - virtual bool writeXml( QDomNode &layer_node, QDomDocument &doc, const QgsReadWriteContext &context ) const; -%Docstring - Write layer specific state to project file Dom node -%End }; diff --git a/python/core/raster/qgsrastershader.sip.in b/python/core/raster/qgsrastershader.sip.in index b5def4247276..e5c1cb0c994e 100644 --- a/python/core/raster/qgsrastershader.sip.in +++ b/python/core/raster/qgsrastershader.sip.in @@ -24,25 +24,43 @@ Interface for all raster shaders. QgsRasterShader( double minimumValue = 0.0, double maximumValue = 255.0 ); - double maximumValue(); + + double maximumValue() const; %Docstring - Return the maximum value for the raster shader +Returns the maximum value for the raster shader. + +.. seealso:: :py:func:`setMaximumValue` + +.. seealso:: :py:func:`minimumValue` %End - double minimumValue(); + double minimumValue() const; %Docstring - Return the minimum value for the raster shader +Returns the minimum value for the raster shader. + +.. seealso:: :py:func:`setMinimumValue` + +.. seealso:: :py:func:`maximumValue` %End QgsRasterShaderFunction *rasterShaderFunction(); + bool shade( double value, int *returnRedValue /Out/, int *returnGreenValue /Out/, int *returnBlueValue /Out/, int *returnAlpha /Out/ ); %Docstring - generates and new RGBA value based on one input value +Generates a new RGBA value based on one input ``value``. + +:param value: The original value to base a new RGBA value on +:param returnRedValue: The red component of the new RGBA value +:param returnGreenValue: The green component of the new RGBA value +:param returnBlueValue: The blue component of the new RGBA value +:param returnAlpha: The alpha component of the new RGBA value + +:return: True if the return values are valid otherwise false %End bool shade( double redValue, @@ -54,26 +72,45 @@ Interface for all raster shaders. int *returnBlueValue /Out/, int *returnAlpha /Out/ ); %Docstring - generates and new RGBA value based on original RGBA value +Generates a new RGBA value based on an original RGBA value. + +:param redValue: The red component of the original value to base a new RGBA value on +:param greenValue: The green component of the original value to base a new RGBA value on +:param blueValue: The blue component of the original value to base a new RGBA value on +:param alphaValue: The alpha component of the original value to base a new RGBA value on +:param returnRedValue: The red component of the new RGBA value +:param returnGreenValue: The green component of the new RGBA value +:param returnBlueValue: The blue component of the new RGBA value +:param returnAlphaValue: The alpha component of the new RGBA value + +:return: True if the return values are valid otherwise false %End void setRasterShaderFunction( QgsRasterShaderFunction *function /Transfer/ ); %Docstring - A public method that allows the user to set their own shader function + A public method that allows the user to set their own shader ``function``. .. note:: - Raster shader takes ownership of the shader function instance * + Raster shader takes ownership of the shader function instance %End - void setMaximumValue( double ); + void setMaximumValue( double value ); %Docstring - Set the maximum value +Sets the maximum ``value`` for the raster shader. + +.. seealso:: :py:func:`setMinimumValue` + +.. seealso:: :py:func:`maximumValue` %End - void setMinimumValue( double ); + void setMinimumValue( double value ); %Docstring - Return the minimum value +Sets the minimum ``value`` for the raster shader. + +.. seealso:: :py:func:`setMaximumValue` + +.. seealso:: :py:func:`minimumValue` %End void writeXml( QDomDocument &doc, QDomElement &parent ) const; diff --git a/python/core/raster/qgsrastershaderfunction.sip.in b/python/core/raster/qgsrastershaderfunction.sip.in index 71a22b4d43ba..7f2a775d849e 100644 --- a/python/core/raster/qgsrastershaderfunction.sip.in +++ b/python/core/raster/qgsrastershaderfunction.sip.in @@ -32,14 +32,22 @@ typically used to render grayscale images as false color. QgsRasterShaderFunction( double minimumValue = 0.0, double maximumValue = 255.0 ); virtual ~QgsRasterShaderFunction(); - virtual void setMaximumValue( double ); + virtual void setMaximumValue( double value ); %Docstring - Set the maximum value +Sets the maximum ``value`` for the raster shader. + +.. seealso:: :py:func:`setMinimumValue` + +.. seealso:: :py:func:`maximumValue` %End - virtual void setMinimumValue( double ); + virtual void setMinimumValue( double value ); %Docstring - Return the minimum value +Sets the minimum ``value`` for the raster shader. + +.. seealso:: :py:func:`setMaximumValue` + +.. seealso:: :py:func:`minimumValue` %End virtual bool shade( double value, @@ -48,7 +56,15 @@ typically used to render grayscale images as false color. int *returnBlueValue /Out/, int *returnAlpha /Out/ ); %Docstring - generates and new RGBA value based on one input value +Generates an new RGBA value based on one input ``value``. + +:param value: The original value to base a new RGBA value on +:param returnRedValue: The red component of the new RGBA value +:param returnGreenValue: The green component of the new RGBA value +:param returnBlueValue: The blue component of the new RGBA value +:param returnAlphaValue: The blue component of the new RGBA value + +:return: True if the return values are valid otherwise false %End virtual bool shade( double redValue, @@ -60,13 +76,39 @@ typically used to render grayscale images as false color. int *returnBlueValue /Out/, int *returnAlpha /Out/ ); %Docstring - generates and new RGBA value based on original RGBA value +Generates an new RGBA value based on an original RGBA value. + +:param redValue: The red component of the original value to base a new RGBA value on +:param greenValue: The green component of the original value to base a new RGBA value on +:param blueValue: The blue component of the original value to base a new RGBA value on +:param alphaValue: The alpha component of the original value to base a new RGBA value on +:param returnRedValue: The red component of the new RGBA value +:param returnGreenValue: The green component of the new RGBA value +:param returnBlueValue: The blue component of the new RGBA value +:param returnAlphaValue: The alpha component of the new RGBA value + +:return: True if the return values are valid otherwise false %End double minimumMaximumRange() const; double minimumValue() const; +%Docstring +Returns the maximum value for the raster shader. + +.. seealso:: :py:func:`setMaximumValue` + +.. seealso:: :py:func:`minimumValue` +%End + double maximumValue() const; +%Docstring +Returns the minimum value for the raster shader. + +.. seealso:: :py:func:`setMinimumValue` + +.. seealso:: :py:func:`maximumValue` +%End virtual void legendSymbologyItems( QList< QPair< QString, QColor > > &symbolItems /Out/ ) const; diff --git a/python/core/raster/qgsrastertransparency.sip.in b/python/core/raster/qgsrastertransparency.sip.in index 2ffac5b10b44..b7196660350b 100644 --- a/python/core/raster/qgsrastertransparency.sip.in +++ b/python/core/raster/qgsrastertransparency.sip.in @@ -50,34 +50,49 @@ Constructor for QgsRasterTransparency. Accessor for transparentThreeValuePixelList %End - void initializeTransparentPixelList( double ); + void initializeTransparentPixelList( double value ); %Docstring - Reset to the transparency list to a single value +Resets the transparency list to a single ``value``. %End - void initializeTransparentPixelList( double, double, double ); + void initializeTransparentPixelList( double redValue, double greenValue, double blueValue ); %Docstring - Reset to the transparency list to a single value +Resets the transparency list to single red, green, and blue values. %End void setTransparentSingleValuePixelList( const QList &newList /Transfer/ ); %Docstring - Mutator for transparentSingleValuePixelList + Mutator for transparentSingleValuePixelList, replaces the whole list %End void setTransparentThreeValuePixelList( const QList &newList /Transfer/ ); %Docstring - Mutator for transparentThreeValuePixelList + Mutator for transparentThreeValuePixelList, replaces the whole list %End - int alphaValue( double, int globalTransparency = 255 ) const; + int alphaValue( double value, int globalTransparency = 255 ) const; %Docstring - Returns the transparency value for a single value Pixel +Returns the transparency value for a single ``value`` pixel. + +Searches through the transparency list, and if a match is found, the global transparency value is scaled +by the stored transparency value. + +:param value: the needle to search for in the transparency hay stack +:param globalTransparency: the overal transparency level for the layer %End - int alphaValue( double, double, double, int globalTransparency = 255 ) const; + + int alphaValue( double redValue, double greenValue, double blueValue, int globalTransparency = 255 ) const; %Docstring - Return the transparency value for a RGB Pixel +Returns the transparency value for a RGB pixel. + +Searches through the transparency list, if a match is found, the global transparency value is scaled +by the stored transparency value. + +:param redValue: the red portion of the needle to search for in the transparency hay stack +:param greenValue: the green portion of the needle to search for in the transparency hay stack +:param blueValue: the green portion of the needle to search for in the transparency hay stack +:param globalTransparency: the overal transparency level for the layer %End bool isEmpty() const; diff --git a/python/gui/qgsattributeeditorcontext.sip.in b/python/gui/qgsattributeeditorcontext.sip.in index 6959c14b1cce..133ba28f88d3 100644 --- a/python/gui/qgsattributeeditorcontext.sip.in +++ b/python/gui/qgsattributeeditorcontext.sip.in @@ -49,32 +49,43 @@ Constructor for QgsAttributeEditorContext void setDistanceArea( const QgsDistanceArea &distanceArea ); %Docstring -Sets distance area object for area/length calculations +Sets distance area object, ``distanceArea``, for area/length calculations -:param distanceArea: map canvas - -.. seealso:: :py:func:`setDistanceArea` +.. seealso:: :py:func:`distanceArea` .. versionadded:: 2.2 %End const QgsDistanceArea &distanceArea() const; +%Docstring +Returns the distance area object used for area/length calculations. + +.. seealso:: :py:func:`setDistanceArea` + +.. versionadded:: 2.2 +%End void setMapCanvas( QgsMapCanvas *mapCanvas ); %Docstring -Sets the map canvas (e.g. to zoom to related features) - -:param mapCanvas: map canvas +Sets the associated map canvas, ``mapCanvas``, (e.g. to zoom to related features). .. seealso:: :py:func:`mapCanvas` .. versionadded:: 3.2 %End + QgsMapCanvas *mapCanvas() const; +%Docstring +Returns the associated map canvas (e.g. to zoom to related features). + +.. seealso:: :py:func:`setMapCanvas` + +.. versionadded:: 3.2 +%End void setVectorLayerTools( QgsVectorLayerTools *vlTools ); %Docstring -Sets the vector layer tools +Sets the associated vector layer tools. :param vlTools: vector layer tools @@ -82,7 +93,15 @@ Sets the vector layer tools .. versionadded:: 2.2 %End + const QgsVectorLayerTools *vectorLayerTools() const; +%Docstring +Returns the associated vector layer tools. + +.. seealso:: :py:func:`setVectorLayerTools` + +.. versionadded:: 2.2 +%End void setRelation( const QgsRelation &relation, RelationMode mode ); %Docstring @@ -97,8 +116,28 @@ Set attribute relation and mode .. versionadded:: 2.6 %End + const QgsRelation &relation() const; +%Docstring +Returns the attribute relation. + +.. seealso:: :py:func:`setRelation` + +.. seealso:: :py:func:`relationMode` + +.. versionadded:: 2.6 +%End + RelationMode relationMode() const; +%Docstring +Returns the attribute relation mode. + +.. seealso:: :py:func:`setRelation` + +.. seealso:: :py:func:`relation` + +.. versionadded:: 2.6 +%End FormMode formMode() const; %Docstring diff --git a/src/app/qgisapp.cpp b/src/app/qgisapp.cpp index 0d4a6f2226fe..94d95feb37ab 100644 --- a/src/app/qgisapp.cpp +++ b/src/app/qgisapp.cpp @@ -584,7 +584,7 @@ void QgisApp::activeLayerChanged( QgsMapLayer *layer ) } } -/** +/* * This function contains forced validation of CRS used in QGIS. * There are 3 options depending on the settings: * - ask for CRS using projection selecter @@ -3008,26 +3008,26 @@ void QgisApp::setIconSizes( int size ) void QgisApp::setTheme( const QString &themeName ) { - /***************************************************************** - // Init the toolbar icons by setting the icon for each action. - // All toolbar/menu items must be a QAction in order for this - // to work. - // - // When new toolbar/menu QAction objects are added to the interface, - // add an entry below to set the icon - // - // PNG names must match those defined for the default theme. The - // default theme is installed in /share/qgis/themes/default. - // - // New core themes can be added by creating a subdirectory under src/themes - // and modifying the appropriate CMakeLists.txt files. User contributed themes - // will be installed directly into /share/qgis/themes/. - // - // Themes can be selected from the preferences dialog. The dialog parses - // the themes directory and builds a list of themes (ie subdirectories) - // for the user to choose from. - // + /* + Init the toolbar icons by setting the icon for each action. + All toolbar/menu items must be a QAction in order for this + to work. + + When new toolbar/menu QAction objects are added to the interface, + add an entry below to set the icon + + PNG names must match those defined for the default theme. The + default theme is installed in /share/qgis/themes/default. + + New core themes can be added by creating a subdirectory under src/themes + and modifying the appropriate CMakeLists.txt files. User contributed themes + will be installed directly into /share/qgis/themes/. + + Themes can be selected from the preferences dialog. The dialog parses + the themes directory and builds a list of themes (ie subdirectories) + for the user to choose from. */ + QgsApplication::setUITheme( themeName ); //QgsDebugMsg("Setting theme to \n" + themeName); mActionNewProject->setIcon( QgsApplication::getThemeIcon( QStringLiteral( "/mActionFileNew.svg" ) ) ); @@ -5511,10 +5511,6 @@ void QgisApp::enableProjectMacros() QgsPythonRunner::run( QStringLiteral( "qgis.utils.reloadProjectMacros()" ) ); } -/** - adds a saved project to qgis, usually called on startup by specifying a - project file on the command line - */ bool QgisApp::addProject( const QString &projectFile ) { MAYBE_UNUSED QgsProjectDirtyBlocker dirtyBlocker( QgsProject::instance() ); @@ -5944,11 +5940,6 @@ void QgisApp::runScript( const QString &filePath ) #endif } - -/** - Open the specified project file; prompt to save previous project if necessary. - Used to process a commandline argument or OpenDocument AppleEvent. - */ void QgisApp::openProject( const QString &fileName ) { if ( checkTasksDependOnProject() ) @@ -5962,11 +5953,6 @@ 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 - */ bool QgisApp::openLayer( const QString &fileName, bool allowInteractive ) { QFileInfo fileInfo( fileName ); @@ -10534,10 +10520,6 @@ void QgisApp::setExtent( const QgsRectangle &rect ) mMapCanvas->setExtent( rect ); } -/** - Prompt and save if project has been modified. - \return true if saved or discarded, false if canceled - */ bool QgisApp::saveDirty() { QString whyDirty; @@ -11680,7 +11662,7 @@ void QgisApp::activateDeactivateLayerRelatedActions( QgsMapLayer *layer ) mActionCopyLayer->setEnabled( true ); mActionPasteLayer->setEnabled( clipboard()->hasFormat( QGSCLIPBOARD_MAPLAYER_MIME ) ); - /***********Vector layers****************/ + // Vector layers if ( layer->type() == QgsMapLayer::VectorLayer ) { QgsVectorLayer *vlayer = qobject_cast( layer ); @@ -11896,7 +11878,7 @@ void QgisApp::activateDeactivateLayerRelatedActions( QgsMapLayer *layer ) mActionLayerSubsetString->setEnabled( false ); } } //end vector layer block - /*************Raster layers*************/ + // Raster layers else if ( layer->type() == QgsMapLayer::RasterLayer ) { const QgsRasterLayer *rlayer = qobject_cast( layer ); diff --git a/src/app/qgisapp.h b/src/app/qgisapp.h index 356739b7ab63..aa515c29fbdb 100644 --- a/src/app/qgisapp.h +++ b/src/app/qgisapp.h @@ -210,11 +210,11 @@ class APP_EXPORT QgisApp : public QMainWindow, private Ui::MainWindow /** * Open a raster or vector file; ignore other files. - Used to process a commandline argument, FileOpen or Drop event. - Set interactive to true if it is OK to ask the user for information (mostly for - when a vector layer has sublayers and we want to ask which sublayers to use). - \returns true if the file is successfully opened - */ + * Used to process a commandline argument, FileOpen or Drop event. + * Set \a allowInteractive to true if it is OK to ask the user for information (mostly for + * when a vector layer has sublayers and we want to ask which sublayers to use). + * \returns true if the file is successfully opened + */ bool openLayer( const QString &fileName, bool allowInteractive = false ); /** @@ -238,9 +238,9 @@ class APP_EXPORT QgisApp : public QMainWindow, private Ui::MainWindow void runScript( const QString &filePath ); /** - * Opens a qgis project file - \returns false if unable to open the project - */ + * Opens a QGIS project file + * \returns false if unable to open the project + */ bool addProject( const QString &projectFile ); //!Overloaded version of the private function with same name that takes the imagename as a parameter @@ -994,7 +994,9 @@ class APP_EXPORT QgisApp : public QMainWindow, private Ui::MainWindow void onSnappingConfigChanged(); - //! validate a SRS + /** + * Triggers validation of the specified \a crs. + */ void validateCrs( QgsCoordinateReferenceSystem &crs ); //! QGIS Sponsors @@ -1749,7 +1751,11 @@ class APP_EXPORT QgisApp : public QMainWindow, private Ui::MainWindow //void readWKB(const char *, QStringList tables); //! shows the paste-transformations dialog // void pasteTransformations(); - //! check to see if file is dirty and if so, prompt the user th save it + + /** + * Check to see if the current project file is dirty and if so, prompt the user to save it. + * \returns true if saved or discarded, false if canceled + */ bool saveDirty(); //! Checks for running tasks dependent on the open project bool checkTasksDependOnProject(); diff --git a/src/app/qgsdecorationnortharrow.cpp b/src/app/qgsdecorationnortharrow.cpp index cb4b00271e73..be76bada6ea1 100644 --- a/src/app/qgsdecorationnortharrow.cpp +++ b/src/app/qgsdecorationnortharrow.cpp @@ -49,12 +49,6 @@ email : tim@linfiniti.com 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 - */ QgsDecorationNorthArrow::QgsDecorationNorthArrow( QObject *parent ) : QgsDecorationItem( parent ) { diff --git a/src/app/qgsdecorationnortharrow.h b/src/app/qgsdecorationnortharrow.h index 7b357d8c5f2a..a272cffc2ae4 100644 --- a/src/app/qgsdecorationnortharrow.h +++ b/src/app/qgsdecorationnortharrow.h @@ -33,7 +33,10 @@ class APP_EXPORT QgsDecorationNorthArrow: public QgsDecorationItem Q_OBJECT public: - //! Constructor + + /** + * Constructor for QgsDecorationNorthArrow, with the specified \a parent object. + */ QgsDecorationNorthArrow( QObject *parent = nullptr ); public slots: diff --git a/src/app/qgsversionmigration.cpp b/src/app/qgsversionmigration.cpp index 464d8a68a7eb..e6daeafd10a7 100644 --- a/src/app/qgsversionmigration.cpp +++ b/src/app/qgsversionmigration.cpp @@ -33,11 +33,11 @@ #include #include -QgsVersionMigration *QgsVersionMigration::canMigrate( int fromVersion, int toVersion ) +std::unique_ptr QgsVersionMigration::canMigrate( int fromVersion, int toVersion ) { if ( fromVersion == 20000 && toVersion >= 29900 ) { - return new Qgs2To3Migration(); + return qgis::make_unique< Qgs2To3Migration >(); } return nullptr; } diff --git a/src/app/qgsversionmigration.h b/src/app/qgsversionmigration.h index 7bfbb92e9466..83a8bb9926a1 100644 --- a/src/app/qgsversionmigration.h +++ b/src/app/qgsversionmigration.h @@ -18,7 +18,7 @@ #include "qgis_app.h" #include "qgserror.h" - +#include #include class QgsSettings; @@ -33,13 +33,16 @@ class APP_EXPORT QgsVersionMigration QgsVersionMigration() = default; virtual ~QgsVersionMigration() = default; + QgsVersionMigration( const QgsVersionMigration &other ) = delete; + QgsVersionMigration &operator=( const QgsVersionMigration &other ) = delete; + /** * Check if two version has a migration options. * \param fromVersion The version migrating from. * \param toVersion The version migrating to. - * \returns migration object + * \returns new migration object */ - static QgsVersionMigration *canMigrate( int fromVersion, int toVersion ); + static std::unique_ptr< QgsVersionMigration > canMigrate( int fromVersion, int toVersion ); /** * Run the version migration to convert between versions. @@ -65,9 +68,9 @@ class Qgs2To3Migration : public QgsVersionMigration QString migrationFilePath(); - int mMigrationFileVersion; + int mMigrationFileVersion = 0; - QSettings *mOldSettings; + QSettings *mOldSettings = nullptr; }; diff --git a/src/core/expression/qgsexpressionfunction.h b/src/core/expression/qgsexpressionfunction.h index 62570f817cdc..92a0a26b9794 100644 --- a/src/core/expression/qgsexpressionfunction.h +++ b/src/core/expression/qgsexpressionfunction.h @@ -289,10 +289,18 @@ class CORE_EXPORT QgsExpressionFunction */ virtual QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) = 0; + /** + * Evaluates the function, first evaluating all required arguments before passing them to the + * function's func() method. + */ virtual QVariant run( QgsExpressionNode::NodeList *args, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ); bool operator==( const QgsExpressionFunction &other ) const; + /** + * Returns true if the function handles NULL values in arguments by itself, and the default + * NULL value handling should be skipped. + */ virtual bool handlesNull() const; protected: @@ -386,8 +394,8 @@ class QgsStaticExpressionFunction : public QgsExpressionFunction FcnEval fcn, const QString &group, const QString &helpText, - const std::function< bool( const QgsExpressionNodeFunction * )> &usesGeometry, - const std::function< QSet( const QgsExpressionNodeFunction * )> &referencedColumns, + const std::function< bool( const QgsExpressionNodeFunction *node )> &usesGeometry, + const std::function< QSet( const QgsExpressionNodeFunction *node )> &referencedColumns, bool lazyEval = false, const QStringList &aliases = QStringList(), bool handlesNull = false ); @@ -419,6 +427,7 @@ class QgsStaticExpressionFunction : public QgsExpressionFunction * \param values list of values passed to the function * \param context context expression is being evaluated against * \param parent parent expression + * \param node function node * \returns result of function */ QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) override @@ -461,6 +470,9 @@ class QgsStaticExpressionFunction : public QgsExpressionFunction */ void setPrepareFunction( const std::function< bool( const QgsExpressionNodeFunction *, QgsExpression *, const QgsExpressionContext * )> &prepareFunc ); + /** + * Returns a list of all registered expression functions. + */ static const QList &functions(); private: @@ -480,6 +492,7 @@ class QgsStaticExpressionFunction : public QgsExpressionFunction * It temporarily appends a new scope to the expression context for all nested * nodes. * + * \ingroup core * \note Not available in Python bindings * \since QGIS 3.0 */ diff --git a/src/core/expression/qgsexpressionnode.h b/src/core/expression/qgsexpressionnode.h index 1346a89a8ce0..bd9918a1eec1 100644 --- a/src/core/expression/qgsexpressionnode.h +++ b/src/core/expression/qgsexpressionnode.h @@ -69,6 +69,8 @@ class CORE_EXPORT QgsExpressionNode SIP_ABSTRACT Q_DECLARE_TR_FUNCTIONS( QgsExpressionNode ); public: + + //! Known node types. enum NodeType { ntUnaryOperator, //!< \see QgsExpression::Node::NodeUnaryOperator @@ -108,6 +110,7 @@ class CORE_EXPORT QgsExpressionNode SIP_ABSTRACT }; /** + * A list of expression nodes. * \ingroup core */ class CORE_EXPORT NodeList @@ -155,6 +158,9 @@ class CORE_EXPORT QgsExpressionNode SIP_ABSTRACT //! Creates a deep copy of this list. Ownership is transferred to the caller QgsExpressionNode::NodeList *clone() const SIP_FACTORY; + /** + * Returns a string dump of the expression node. + */ virtual QString dump() const; private: diff --git a/src/core/expression/qgsexpressionnodeimpl.h b/src/core/expression/qgsexpressionnodeimpl.h index 52f7016cdef0..648c8e314c24 100644 --- a/src/core/expression/qgsexpressionnodeimpl.h +++ b/src/core/expression/qgsexpressionnodeimpl.h @@ -47,7 +47,14 @@ class CORE_EXPORT QgsExpressionNodeUnaryOperator : public QgsExpressionNode {} ~QgsExpressionNodeUnaryOperator() override { delete mOperand; } + /** + * Returns the unary operator. + */ QgsExpressionNodeUnaryOperator::UnaryOperator op() const { return mOp; } + + /** + * Returns the node the operator will operate upon. + */ QgsExpressionNode *operand() const { return mOperand; } QgsExpressionNode::NodeType nodeType() const override; @@ -76,6 +83,7 @@ class CORE_EXPORT QgsExpressionNodeUnaryOperator : public QgsExpressionNode }; /** + * A binary expression operator, which operates on two values. * \ingroup core */ class CORE_EXPORT QgsExpressionNodeBinaryOperator : public QgsExpressionNode @@ -130,8 +138,21 @@ class CORE_EXPORT QgsExpressionNodeBinaryOperator : public QgsExpressionNode {} ~QgsExpressionNodeBinaryOperator() override { delete mOpLeft; delete mOpRight; } + /** + * Returns the binary operator. + */ QgsExpressionNodeBinaryOperator::BinaryOperator op() const { return mOp; } + + /** + * Returns the node to the left of the operator. + * \see opRight() + */ QgsExpressionNode *opLeft() const { return mOpLeft; } + + /** + * Returns the node to the right of the operator. + * \see opLeft() + */ QgsExpressionNode *opRight() const { return mOpRight; } QgsExpressionNode::NodeType nodeType() const override; @@ -145,7 +166,14 @@ class CORE_EXPORT QgsExpressionNodeBinaryOperator : public QgsExpressionNode QgsExpressionNode *clone() const override SIP_FACTORY; bool isStatic( QgsExpression *parent, const QgsExpressionContext *context ) const override; + /** + * Returns the precedence index for the operator. Higher values have higher precedence. + */ int precedence() const; + + /** + * Returns true if the operator is left-associative. + */ bool leftAssociative() const; /** @@ -174,6 +202,7 @@ class CORE_EXPORT QgsExpressionNodeBinaryOperator : public QgsExpressionNode }; /** + * An expression node for value IN or NOT IN clauses. * \ingroup core */ class CORE_EXPORT QgsExpressionNodeInOperator : public QgsExpressionNode @@ -190,8 +219,19 @@ class CORE_EXPORT QgsExpressionNodeInOperator : public QgsExpressionNode {} ~QgsExpressionNodeInOperator() override; + /** + * Returns the expression node. + */ QgsExpressionNode *node() const { return mNode; } + + /** + * Returns true if this node is a "NOT IN" operator, or false if the node is a normal "IN" operator. + */ bool isNotIn() const { return mNotIn; } + + /** + * Returns the list of nodes to search for matching values within. + */ QgsExpressionNode::NodeList *list() const { return mList; } QgsExpressionNode::NodeType nodeType() const override; @@ -212,6 +252,7 @@ class CORE_EXPORT QgsExpressionNodeInOperator : public QgsExpressionNode }; /** + * An expression node for expression functions. * \ingroup core */ class CORE_EXPORT QgsExpressionNodeFunction : public QgsExpressionNode @@ -226,7 +267,14 @@ class CORE_EXPORT QgsExpressionNodeFunction : public QgsExpressionNode ~QgsExpressionNodeFunction() override; + /** + * Returns the index of the node's function. + */ int fnIndex() const { return mFnIndex; } + + /** + * Returns a list of arguments specified for the function. + */ QgsExpressionNode::NodeList *args() const { return mArgs; } QgsExpressionNode::NodeType nodeType() const override; @@ -249,11 +297,16 @@ class CORE_EXPORT QgsExpressionNodeFunction : public QgsExpressionNode }; /** + * An expression node for literal values. * \ingroup core */ class CORE_EXPORT QgsExpressionNodeLiteral : public QgsExpressionNode { public: + + /** + * Constructor for QgsExpressionNodeLiteral, with the specified literal \a value. + */ QgsExpressionNodeLiteral( const QVariant &value ) : mValue( value ) {} @@ -277,11 +330,17 @@ class CORE_EXPORT QgsExpressionNodeLiteral : public QgsExpressionNode }; /** + * An expression node which takes it value from a feature's field. * \ingroup core */ class CORE_EXPORT QgsExpressionNodeColumnRef : public QgsExpressionNode { public: + + /** + * Constructor for QgsExpressionNodeColumnRef, referencing the column + * with the specified \a name. + */ QgsExpressionNodeColumnRef( const QString &name ) : mName( name ) , mIndex( -1 ) @@ -308,11 +367,17 @@ class CORE_EXPORT QgsExpressionNodeColumnRef : public QgsExpressionNode }; /** + * An expression node for CASE WHEN clauses. * \ingroup core */ class CORE_EXPORT QgsExpressionNodeCondition : public QgsExpressionNode { public: + + /** + * Represents a "WHEN... THEN..." portation of a CASE WHEN clause in an expression. + * \ingroup core + */ class CORE_EXPORT WhenThen { public: diff --git a/src/core/expression/qgsexpressionutils.cpp b/src/core/expression/qgsexpressionutils.cpp index ecbae1cf09df..77f7c30e4287 100644 --- a/src/core/expression/qgsexpressionutils.cpp +++ b/src/core/expression/qgsexpressionutils.cpp @@ -16,6 +16,8 @@ #include "qgsexpressionutils.h" #include "qgsexpressionnode.h" +///@cond PRIVATE + QgsExpressionUtils::TVL QgsExpressionUtils::AND[3][3] = { // false true unknown @@ -31,3 +33,5 @@ QgsExpressionUtils::TVL QgsExpressionUtils::OR[3][3] = }; QgsExpressionUtils::TVL QgsExpressionUtils::NOT[3] = { True, False, Unknown }; + +///@endcond diff --git a/src/core/expression/qgsexpressionutils.h b/src/core/expression/qgsexpressionutils.h index a19acf887e31..1d843c596794 100644 --- a/src/core/expression/qgsexpressionutils.h +++ b/src/core/expression/qgsexpressionutils.h @@ -36,7 +36,7 @@ /////////////////////////////////////////////// // three-value logic -/// @cond +/// @cond PRIVATE class QgsExpressionUtils { public: diff --git a/src/core/pal/pal.h b/src/core/pal/pal.h index ce2c0b42bdca..f617d20d8575 100644 --- a/src/core/pal/pal.h +++ b/src/core/pal/pal.h @@ -118,8 +118,6 @@ namespace pal * \param displayAll if true, all features will be labelled even though overlaps occur * * \throws PalException::LayerExists - * - * \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/qgssqlstatement.h b/src/core/qgssqlstatement.h index 30f61d4d959f..f5697947ab28 100644 --- a/src/core/qgssqlstatement.h +++ b/src/core/qgssqlstatement.h @@ -279,8 +279,9 @@ class CORE_EXPORT QgsSQLStatement }; /** + * A list of nodes. * \ingroup core - * List of nodes */ + */ class CORE_EXPORT NodeList { public: diff --git a/src/core/qgsvectorlayer.h b/src/core/qgsvectorlayer.h index 4ad43ebcffd7..dc8d4be71e56 100644 --- a/src/core/qgsvectorlayer.h +++ b/src/core/qgsvectorlayer.h @@ -2283,8 +2283,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? + * \param provider provider key string, must match a valid QgsVectorDataProvider key. E.g. "postgres", "ogr", etc. */ bool setDataProvider( QString const &provider ); diff --git a/src/core/qgsvectorlayerundopassthroughcommand.cpp b/src/core/qgsvectorlayerundopassthroughcommand.cpp index 063634bb72e6..bb0254efe9c6 100644 --- a/src/core/qgsvectorlayerundopassthroughcommand.cpp +++ b/src/core/qgsvectorlayerundopassthroughcommand.cpp @@ -26,7 +26,7 @@ #include -//\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 ) diff --git a/src/core/raster/qgscontrastenhancement.cpp b/src/core/raster/qgscontrastenhancement.cpp index 3fa3898addd8..d7d3c128b844 100644 --- a/src/core/raster/qgscontrastenhancement.cpp +++ b/src/core/raster/qgscontrastenhancement.cpp @@ -77,9 +77,6 @@ QgsContrastEnhancement::~QgsContrastEnhancement() * */ -/** - Simple function to compute the maximum possible value for a data types. -*/ double QgsContrastEnhancement::maximumValuePossible( Qgis::DataType dataType ) { switch ( dataType ) @@ -116,9 +113,6 @@ double QgsContrastEnhancement::maximumValuePossible( Qgis::DataType dataType ) return std::numeric_limits::max(); } -/** - Simple function to compute the minimum possible value for a data type. -*/ double QgsContrastEnhancement::minimumValuePossible( Qgis::DataType dataType ) { switch ( dataType ) @@ -161,11 +155,6 @@ double QgsContrastEnhancement::minimumValuePossible( Qgis::DataType dataType ) * */ -/** - Public function to generate the enhanced for enhanceContrasted value for a given input. - - \param value The pixel value to enhance -*/ int QgsContrastEnhancement::enhanceContrast( double value ) { if ( mEnhancementDirty ) @@ -189,9 +178,6 @@ int QgsContrastEnhancement::enhanceContrast( double value ) } } -/** - Generate a new lookup table -*/ bool QgsContrastEnhancement::generateLookupTable() { mEnhancementDirty = false; @@ -219,11 +205,6 @@ bool QgsContrastEnhancement::generateLookupTable() return true; } -/** - Determine if a pixel is within in the displayable range. - - \param value The pixel value to examine -*/ bool QgsContrastEnhancement::isValueInDisplayableRange( double value ) { if ( mContrastEnhancementFunction ) @@ -234,12 +215,6 @@ bool QgsContrastEnhancement::isValueInDisplayableRange( double value ) return false; } -/** - Set the contrast enhancement algorithm. The second 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. - - \param algorithm The new contrast enhancement algorithm - \param generateTable Flag to override automatic look up table generation -*/ void QgsContrastEnhancement::setContrastEnhancementAlgorithm( ContrastEnhancementAlgorithm algorithm, bool generateTable ) { switch ( algorithm ) @@ -270,11 +245,6 @@ void QgsContrastEnhancement::setContrastEnhancementAlgorithm( ContrastEnhancemen } } -/** - A public function that allows the user to set their own custom contrast enhancement function. - - \param function The new contrast enhancement function -*/ void QgsContrastEnhancement::setContrastEnhancementFunction( QgsContrastEnhancementFunction *function ) { QgsDebugMsgLevel( "called", 4 ); @@ -287,12 +257,6 @@ void QgsContrastEnhancement::setContrastEnhancementFunction( QgsContrastEnhancem } } -/** - Set the maximum value for the contrast enhancement. The second parameter is option an 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 tale. By default it will be generated. - - \param value The new maximum value for the band - \param generateTable Flag to override automatic look up table generation -*/ void QgsContrastEnhancement::setMaximumValue( double value, bool generateTable ) { QgsDebugMsgLevel( "called value: " + QString::number( value ) + " generate lookup table: " + QString::number( static_cast< int >( generateTable ) ), 4 ); @@ -319,12 +283,6 @@ void QgsContrastEnhancement::setMaximumValue( double value, bool generateTable ) } } -/** - Set the maximum value for the contrast enhancement. The second parameter is option an 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 tale. By default it will be generated. - - \param value The new minimum value for the band - \param generateTable Flag to override automatic look up table generation -*/ void QgsContrastEnhancement::setMinimumValue( double value, bool generateTable ) { QgsDebugMsgLevel( "called value: " + QString::number( value ) + " generate lookup table: " + QString::number( static_cast< int >( generateTable ) ), 4 ); diff --git a/src/core/raster/qgscontrastenhancement.h b/src/core/raster/qgscontrastenhancement.h index 7671b03f6c3f..420c53e88b3c 100644 --- a/src/core/raster/qgscontrastenhancement.h +++ b/src/core/raster/qgscontrastenhancement.h @@ -65,16 +65,25 @@ class CORE_EXPORT QgsContrastEnhancement * Static methods * */ - //! \brief 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. + */ static double maximumValuePossible( Qgis::DataType ); - //! \brief 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. + */ static double minimumValuePossible( Qgis::DataType ); - //! \brief Return a string to serialize ContrastEnhancementAlgorithm + /** + * Return a string to serialize ContrastEnhancementAlgorithm. + */ static QString contrastEnhancementAlgorithmString( ContrastEnhancementAlgorithm algorithm ); - //! \brief Deserialize ContrastEnhancementAlgorithm + /** + * Deserialize ContrastEnhancementAlgorithm. + */ static ContrastEnhancementAlgorithm contrastEnhancementAlgorithmFromString( const QString &contrastEnhancementString ); /* @@ -95,23 +104,56 @@ class CORE_EXPORT QgsContrastEnhancement * Non-Static methods * */ - //! \brief Apply the contrast enhancement to a value. Return values are 0 - 254, -1 means the pixel was clipped and should not be displayed - int enhanceContrast( double ); - - //! \brief Return true if pixel is in stretable range, false if pixel is outside of range (i.e., clipped) - bool isValueInDisplayableRange( double ); - //! \brief Set the contrast enhancement algorithm - void setContrastEnhancementAlgorithm( ContrastEnhancementAlgorithm, bool generateTable = true ); + /** + * Applies the contrast enhancement to a \a value. Return values are 0 - 254, -1 means the pixel was clipped and should not be displayed. + */ + int enhanceContrast( double value ); - //! \brief A public method that allows the user to set their own custom contrast enhancement function - void setContrastEnhancementFunction( QgsContrastEnhancementFunction * ); + /** + * Return true if a pixel \a value is in displayable range, false if pixel + * is outside of range (i.e. clipped). + */ + bool isValueInDisplayableRange( double value ); - //! \brief Set the maximum value for the contrast enhancement range. - void setMaximumValue( double, bool generateTable = true ); + /** + * Sets the contrast enhancement \a algorithm. + * + * The \a 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. + */ + void setContrastEnhancementAlgorithm( ContrastEnhancementAlgorithm algorithm, bool generateTable = true ); + + /** + * Allows the user to set their own custom contrast enhancement \a function. Ownership of + * \a function is transfered. + */ + void setContrastEnhancementFunction( QgsContrastEnhancementFunction *function SIP_TRANSFER ); + + /** + * Sets the maximum \a value for the contrast enhancement range. + * + * The \a 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. + * + * \see setMinimumValue() + */ + void setMaximumValue( double value, bool generateTable = true ); - //! \brief Return the minimum value for the contrast enhancement range. - void setMinimumValue( double, bool generateTable = true ); + /** + * Sets the minimum \a value for the contrast enhancement range. + * + * The \a 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. + * + * \see setMaximumValue() + */ + void setMinimumValue( double value, bool generateTable = true ); void writeXml( QDomDocument &doc, QDomElement &parentElem ) const; @@ -149,7 +191,7 @@ class CORE_EXPORT QgsContrastEnhancement //! \brief Maximum range of values for a given data type double mRasterDataTypeRange; - //! \brief Method to generate a new lookup table + //! Generates a new lookup table bool generateLookupTable(); //! \brief Method to calculate the actual enhanceContrasted value(s) diff --git a/src/core/raster/qgsrasterlayer.cpp b/src/core/raster/qgsrasterlayer.cpp index 2cdf7546cd0b..584bcf3a455a 100644 --- a/src/core/raster/qgsrasterlayer.cpp +++ b/src/core/raster/qgsrasterlayer.cpp @@ -165,9 +165,6 @@ QgsRasterLayer *QgsRasterLayer::clone() const // ///////////////////////////////////////////////////////// -/** - * This helper checks to see whether the file name appears to be a valid raster file name - */ bool QgsRasterLayer::isValidRasterFileName( const QString &fileNameQString, QString &retErrMsg ) { isvalidrasterfilename_t *pValid = reinterpret_cast< isvalidrasterfilename_t * >( cast_to_fptr( QgsProviderRegistry::instance()->function( "gdal", "isValidRasterFileName" ) ) ); @@ -230,17 +227,11 @@ void QgsRasterLayer::setRendererForDrawingStyle( QgsRaster::DrawingStyle drawing setRenderer( QgsApplication::rasterRendererRegistry()->defaultRendererForDrawingStyle( drawingStyle, mDataProvider ) ); } -/** - * \return 0 if not using the data provider model (i.e. directly using GDAL) - */ QgsRasterDataProvider *QgsRasterLayer::dataProvider() { return mDataProvider; } -/** - * \return 0 if not using the data provider model (i.e. directly using GDAL) - */ const QgsRasterDataProvider *QgsRasterLayer::dataProvider() const { return mDataProvider; @@ -482,11 +473,6 @@ QString QgsRasterLayer::htmlMetadata() const return myMetadata; } - -/** - * \param bandNumber the number of the band to use for generating a pixmap of the associated palette - * \return a 100x100 pixel QPixmap of the bands palette - */ QPixmap QgsRasterLayer::paletteAsPixmap( int bandNumber ) { //TODO: This function should take dimensions @@ -546,9 +532,6 @@ QString QgsRasterLayer::providerType() const return mProviderKey; } -/** - * \return the horizontal units per pixel as reported in the GDAL geotramsform[1] - */ double QgsRasterLayer::rasterUnitsPerPixelX() const { // We return one raster pixel per map unit pixel @@ -1400,14 +1383,8 @@ bool QgsRasterLayer::readSymbology( const QDomNode &layer_node, QString &errorMe bool QgsRasterLayer::readStyle( const QDomNode &node, QString &errorMessage, QgsReadWriteContext &context ) { return readSymbology( node, errorMessage, context ); -} //readSymbology - -/** - - Raster layer project file XML of form: +} - \note Called by QgsMapLayer::readXml(). -*/ bool QgsRasterLayer::readXml( const QDomNode &layer_node, QgsReadWriteContext &context ) { QgsDebugMsgLevel( "Entered", 4 ); diff --git a/src/core/raster/qgsrasterlayer.h b/src/core/raster/qgsrasterlayer.h index 361b39cf3d07..d4638b834a4a 100644 --- a/src/core/raster/qgsrasterlayer.h +++ b/src/core/raster/qgsrasterlayer.h @@ -236,11 +236,13 @@ class CORE_EXPORT QgsRasterLayer : public QgsMapLayer /** * This helper checks to see whether the file name appears to be a valid - * raster file name. If the file name looks like it could be valid, - * but some sort of error occurs in processing the file, the error is - * returned in retError. + * raster file name. If the file name looks like it could be valid, + * but some sort of error occurs in processing the file, the error is + * returned in \a retError. */ static bool isValidRasterFileName( const QString &fileNameQString, QString &retError ); + // TODO QGIS 4.0 - rename fileNameQString to fileName + static bool isValidRasterFileName( const QString &fileNameQString ); //! Return time stamp for given file name @@ -277,21 +279,13 @@ class CORE_EXPORT QgsRasterLayer : public QgsMapLayer //! \brief Get the name of a band given its number QString bandName( int bandNoInt ) const; + // Returns nullptr if not using the data provider model (i.e. directly using GDAL) QgsRasterDataProvider *dataProvider() override; - /** - * Returns the data provider in a const-correct manner - \note available in Python bindings as constDataProvider() - */ + // Returns nullptr if not using the data provider model (i.e. directly using GDAL) const QgsRasterDataProvider *dataProvider() const SIP_PYNAME( constDataProvider ) override; - //! Synchronises with changes in the datasource void reload() override; - - /** - * Return new instance of QgsMapLayerRenderer that will be used for rendering of given context - * \since QGIS 2.4 - */ QgsMapLayerRenderer *createMapRenderer( QgsRenderContext &rendererContext ) override SIP_FACTORY; //! \brief This is an overloaded version of the draw() function that is called by both draw() and thumbnailAsPixmap @@ -306,15 +300,32 @@ class CORE_EXPORT QgsRasterLayer : public QgsMapLayer QString htmlMetadata() const override; - //! \brief Get an 100x100 pixmap of the color palette. If the layer has no palette a white pixmap will be returned + /** + * Returns a 100x100 pixmap of the color palette. If the layer has no palette a white pixmap will be returned + * \param bandNumber the number of the band to use for generating a pixmap of the associated palette + */ QPixmap paletteAsPixmap( int bandNumber = 1 ); //! \brief [ data provider interface ] Which provider is being used for this Raster Layer? QString providerType() const; - //! \brief Returns the number of raster units per each raster pixel in X axis. In a world file, this is normally the first row (without the sign) + /** + * Returns the number of raster units per each raster pixel in X axis. + * + * In a world file, this is normally the first row (without the sign). (E.g. + * the value reported by the GDAL geotransform[1]). + * + * \see rasterUnitsPerPixelY() + */ double rasterUnitsPerPixelX() const; - //! \brief Returns the number of raster units per each raster pixel in Y axis. In a world file, this is normally the first row (without the sign) + + /** + * Returns the number of raster units per each raster pixel in Y axis. + * + * In a world file, this is normally the first row (without the sign). + * + * \see rasterUnitsPerPixelX() + */ double rasterUnitsPerPixelY() const; /** @@ -336,14 +347,12 @@ class CORE_EXPORT QgsRasterLayer : public QgsMapLayer * \brief Refresh contrast enhancement with new extent. * \note not available in Python bindings */ - // Used by QgisApp::legendLayerStretchUsingCurrentExtent() void refreshContrastEnhancement( const QgsRectangle &extent ) SIP_SKIP; /** * \brief Refresh renderer with new extent, if needed * \note not available in Python bindings */ - // Used by QgsRasterLayerRenderer void refreshRendererIfNeeded( QgsRasterRenderer *rasterRenderer, const QgsRectangle &extent ) SIP_SKIP; /** @@ -357,7 +366,6 @@ class CORE_EXPORT QgsRasterLayer : public QgsMapLayer //! \brief Set default contrast enhancement void setDefaultContrastEnhancement(); - //! \brief Returns the sublayers of this layer - Useful for providers that manage their own layers, such as WMS QStringList subLayers() const override; /** @@ -366,42 +374,19 @@ class CORE_EXPORT QgsRasterLayer : public QgsMapLayer QImage previewAsImage( QSize size, const QColor &bgColor = Qt::white, QImage::Format format = QImage::Format_ARGB32_Premultiplied ); - /** - * Reorders the *previously selected* sublayers of this layer from bottom to top - * - * (Useful for providers that manage their own layers, such as WMS) - * - */ void setLayerOrder( const QStringList &layers ) override; - - /** - * Set the visibility of the given sublayer name - */ void setSubLayerVisibility( const QString &name, bool vis ) override; - - //! Time stamp of data source in the moment when data/metadata were loaded by provider QDateTime timestamp() const override; public slots: void showStatusMessage( const QString &message ); protected: - //! \brief Read the symbology for the current layer from the Dom node supplied bool readSymbology( const QDomNode &node, QString &errorMessage, QgsReadWriteContext &context ) override; - - //! \brief Read the style information for the current layer from the Dom node supplied bool readStyle( const QDomNode &node, QString &errorMessage, QgsReadWriteContext &context ) override; - - //! \brief Reads layer specific state from project file Dom node bool readXml( const QDomNode &layer_node, QgsReadWriteContext &context ) override; - - //! \brief Write the symbology for the layer into the docment provided bool writeSymbology( QDomNode &, QDomDocument &doc, QString &errorMessage, const QgsReadWriteContext &context ) const override; - - //! \brief Write the style for the layer into the docment provided bool writeStyle( QDomNode &node, QDomDocument &doc, QString &errorMessage, const QgsReadWriteContext &context ) const override; - - //! \brief Write layer specific state to project file Dom node bool writeXml( QDomNode &layer_node, QDomDocument &doc, const QgsReadWriteContext &context ) const override; private: diff --git a/src/core/raster/qgsrastershader.cpp b/src/core/raster/qgsrastershader.cpp index 01ddacd7bce7..0881660bb384 100644 --- a/src/core/raster/qgsrastershader.cpp +++ b/src/core/raster/qgsrastershader.cpp @@ -33,16 +33,6 @@ QgsRasterShader::QgsRasterShader( double minimumValue, double maximumValue ) QgsDebugMsgLevel( "called.", 4 ); } -/** - Generates and new RGBA value based on one input value - - \param value The original value to base a new RGBA value on - \param returnRedValue The red component of the new RGBA value - \param returnGreenValue The green component of the new RGBA value - \param returnBlueValue The blue component of the new RGBA value - \param returnAlpha The alpha component of the new RGBA value - \return True if the return values are valid otherwise false -*/ bool QgsRasterShader::shade( double value, int *returnRedValue, int *returnGreenValue, int *returnBlueValue, int *returnAlpha ) { if ( mRasterShaderFunction ) @@ -53,20 +43,6 @@ bool QgsRasterShader::shade( double value, int *returnRedValue, int *returnGreen return false; } -/** - Generates and new RGBA value based on an original RGBA value - - - \param redValue The red component of the original value to base a new RGBA value on - \param greenValue The green component of the original value to base a new RGBA value on - \param blueValue The blue component of the original value to base a new RGBA value on - \param alphaValue The alpha component of the original value to base a new RGBA value on - \param returnRedValue The red component of the new RGBA value - \param returnGreenValue The green component of the new RGBA value - \param returnBlueValue The blue component of the new RGBA value - \param returnAlphaValue The alpha component of the new RGBA value - \return True if the return values are valid otherwise false -*/ bool QgsRasterShader::shade( double redValue, double greenValue, double blueValue, double alphaValue, int *returnRedValue, int *returnGreenValue, int *returnBlueValue, int *returnAlphaValue ) { if ( mRasterShaderFunction ) @@ -77,11 +53,6 @@ bool QgsRasterShader::shade( double redValue, double greenValue, double blueValu return false; } -/** - A public function that allows the user to set their own custom shader function. - - \param function A pointer to the new raster shader function -*/ void QgsRasterShader::setRasterShaderFunction( QgsRasterShaderFunction *function ) { QgsDebugMsgLevel( "called.", 4 ); @@ -95,11 +66,6 @@ void QgsRasterShader::setRasterShaderFunction( QgsRasterShaderFunction *function } } -/** - Set the maximum value for the raster shader. - - \param value The new maximum value -*/ void QgsRasterShader::setMaximumValue( double value ) { QgsDebugMsgLevel( "Value = " + QString::number( value ), 4 ); @@ -111,11 +77,6 @@ void QgsRasterShader::setMaximumValue( double value ) } } -/** - Set the maximum value for the raster shader - - \param value The new minimum value -*/ void QgsRasterShader::setMinimumValue( double value ) { QgsDebugMsgLevel( "Value = " + QString::number( value ), 4 ); diff --git a/src/core/raster/qgsrastershader.h b/src/core/raster/qgsrastershader.h index 9d8d5490bbc7..158b0059dbb7 100644 --- a/src/core/raster/qgsrastershader.h +++ b/src/core/raster/qgsrastershader.h @@ -47,11 +47,20 @@ class CORE_EXPORT QgsRasterShader * Non-Static Inline methods * */ - //! \brief Return the maximum value for the raster shader - double maximumValue() { return mMaximumValue; } - //! \brief Return the minimum value for the raster shader - double minimumValue() { return mMinimumValue; } + /** + * Returns the maximum value for the raster shader. + * \see setMaximumValue() + * \see minimumValue() + */ + double maximumValue() const { return mMaximumValue; } + + /** + * Returns the minimum value for the raster shader. + * \see setMinimumValue() + * \see maximumValue() + */ + double minimumValue() const { return mMinimumValue; } QgsRasterShaderFunction *rasterShaderFunction() { return mRasterShaderFunction.get(); } const QgsRasterShaderFunction *rasterShaderFunction() const { return mRasterShaderFunction.get(); } SIP_SKIP @@ -61,14 +70,35 @@ class CORE_EXPORT QgsRasterShader * Non-Static methods * */ - //! \brief generates and new RGBA value based on one input value + + /** + * Generates a new RGBA value based on one input \a value. + * + * \param value The original value to base a new RGBA value on + * \param returnRedValue The red component of the new RGBA value + * \param returnGreenValue The green component of the new RGBA value + * \param returnBlueValue The blue component of the new RGBA value + * \param returnAlpha The alpha component of the new RGBA value + * \return True if the return values are valid otherwise false + */ bool shade( double value, int *returnRedValue SIP_OUT, int *returnGreenValue SIP_OUT, int *returnBlueValue SIP_OUT, int *returnAlpha SIP_OUT ); - //! \brief generates and new RGBA value based on original RGBA value + /** + * Generates a new RGBA value based on an original RGBA value. + * \param redValue The red component of the original value to base a new RGBA value on + * \param greenValue The green component of the original value to base a new RGBA value on + * \param blueValue The blue component of the original value to base a new RGBA value on + * \param alphaValue The alpha component of the original value to base a new RGBA value on + * \param returnRedValue The red component of the new RGBA value + * \param returnGreenValue The green component of the new RGBA value + * \param returnBlueValue The blue component of the new RGBA value + * \param returnAlphaValue The alpha component of the new RGBA value + * \return True if the return values are valid otherwise false + */ bool shade( double redValue, double greenValue, double blueValue, @@ -79,15 +109,24 @@ class CORE_EXPORT QgsRasterShader int *returnAlpha SIP_OUT ); /** - * \brief A public method that allows the user to set their own shader function - \note Raster shader takes ownership of the shader function instance */ + * \brief A public method that allows the user to set their own shader \a function. + * \note Raster shader takes ownership of the shader function instance + */ void setRasterShaderFunction( QgsRasterShaderFunction *function SIP_TRANSFER ); - //! \brief Set the maximum value - void setMaximumValue( double ); + /** + * Sets the maximum \a value for the raster shader. + * \see setMinimumValue() + * \see maximumValue() + */ + void setMaximumValue( double value ); - //! \brief Return the minimum value - void setMinimumValue( double ); + /** + * Sets the minimum \a value for the raster shader. + * \see setMaximumValue() + * \see minimumValue() + */ + void setMinimumValue( double value ); /** * Writes shader state to an XML element. diff --git a/src/core/raster/qgsrastershaderfunction.cpp b/src/core/raster/qgsrastershaderfunction.cpp index c1c681f8fc5d..62ae77d780f9 100644 --- a/src/core/raster/qgsrastershaderfunction.cpp +++ b/src/core/raster/qgsrastershaderfunction.cpp @@ -27,11 +27,6 @@ QgsRasterShaderFunction::QgsRasterShaderFunction( double minimumValue, double ma QgsDebugMsgLevel( "entered.", 4 ); } -/** - Set the maximum value for the raster shader. - - \param value The new maximum value -*/ void QgsRasterShaderFunction::setMaximumValue( double value ) { QgsDebugMsgLevel( "value = " + QString::number( value ), 4 ); @@ -40,11 +35,6 @@ void QgsRasterShaderFunction::setMaximumValue( double value ) mMinimumMaximumRange = mMaximumValue - mMinimumValue; } -/** - Set the maximum value for the raster shader - - \param value The new minimum value -*/ void QgsRasterShaderFunction::setMinimumValue( double value ) { QgsDebugMsgLevel( "value = " + QString::number( value ), 4 ); @@ -53,16 +43,6 @@ void QgsRasterShaderFunction::setMinimumValue( double value ) mMinimumMaximumRange = mMaximumValue - mMinimumValue; } -/** - Generates and new RGBA value based on one input value - - \param value The original value to base a new RGBA value on - \param returnRedValue The red component of the new RGBA value - \param returnGreenValue The green component of the new RGBA value - \param returnBlueValue The blue component of the new RGBA value - \param returnAlphaValue The blue component of the new RGBA value - \return True if the return values are valid otherwise false -*/ bool QgsRasterShaderFunction::shade( double value, int *returnRedValue, int *returnGreenValue, int *returnBlueValue, int *returnAlphaValue ) { Q_UNUSED( value ); @@ -75,20 +55,6 @@ bool QgsRasterShaderFunction::shade( double value, int *returnRedValue, int *ret return false; } -/** - Generates and new RGBA value based on an original RGBA value - - - \param redValue The red component of the original value to base a new RGBA value on - \param greenValue The green component of the original value to base a new RGBA value on - \param blueValue The blue component of the original value to base a new RGBA value on - \param alphaValue The alpha component of the original value to base a new RGBA value on - \param returnRedValue The red component of the new RGBA value - \param returnGreenValue The green component of the new RGBA value - \param returnBlueValue The blue component of the new RGBA value - \param returnAlphaValue The alpha component of the new RGBA value - \return True if the return values are valid otherwise false -*/ bool QgsRasterShaderFunction::shade( double redValue, double greenValue, double blueValue, double alphaValue, int *returnRedValue, int *returnGreenValue, int *returnBlueValue, int *returnAlphaValue ) { Q_UNUSED( redValue ); diff --git a/src/core/raster/qgsrastershaderfunction.h b/src/core/raster/qgsrastershaderfunction.h index f6551ab4b844..218460ec2c97 100644 --- a/src/core/raster/qgsrastershaderfunction.h +++ b/src/core/raster/qgsrastershaderfunction.h @@ -51,20 +51,48 @@ class CORE_EXPORT QgsRasterShaderFunction QgsRasterShaderFunction( double minimumValue = 0.0, double maximumValue = 255.0 ); virtual ~QgsRasterShaderFunction() = default; - //! \brief Set the maximum value - virtual void setMaximumValue( double ); - - //! \brief Return the minimum value - virtual void setMinimumValue( double ); - - //! \brief generates and new RGBA value based on one input value + /** + * Sets the maximum \a value for the raster shader. + * \see setMinimumValue() + * \see maximumValue() + */ + virtual void setMaximumValue( double value ); + + /** + * Sets the minimum \a value for the raster shader. + * \see setMaximumValue() + * \see minimumValue() + */ + virtual void setMinimumValue( double value ); + + /** + * Generates an new RGBA value based on one input \a value. + * \param value The original value to base a new RGBA value on + * \param returnRedValue The red component of the new RGBA value + * \param returnGreenValue The green component of the new RGBA value + * \param returnBlueValue The blue component of the new RGBA value + * \param returnAlphaValue The blue component of the new RGBA value + * \return True if the return values are valid otherwise false + */ virtual bool shade( double value, int *returnRedValue SIP_OUT, int *returnGreenValue SIP_OUT, int *returnBlueValue SIP_OUT, int *returnAlpha SIP_OUT ); - //! \brief generates and new RGBA value based on original RGBA value + /** + * Generates an new RGBA value based on an original RGBA value. + * + * \param redValue The red component of the original value to base a new RGBA value on + * \param greenValue The green component of the original value to base a new RGBA value on + * \param blueValue The blue component of the original value to base a new RGBA value on + * \param alphaValue The alpha component of the original value to base a new RGBA value on + * \param returnRedValue The red component of the new RGBA value + * \param returnGreenValue The green component of the new RGBA value + * \param returnBlueValue The blue component of the new RGBA value + * \param returnAlphaValue The alpha component of the new RGBA value + * \return True if the return values are valid otherwise false + */ virtual bool shade( double redValue, double greenValue, double blueValue, @@ -76,7 +104,18 @@ class CORE_EXPORT QgsRasterShaderFunction double minimumMaximumRange() const { return mMinimumMaximumRange; } + /** + * Returns the maximum value for the raster shader. + * \see setMaximumValue() + * \see minimumValue() + */ double minimumValue() const { return mMinimumValue; } + + /** + * Returns the minimum value for the raster shader. + * \see setMinimumValue() + * \see maximumValue() + */ double maximumValue() const { return mMaximumValue; } virtual void legendSymbologyItems( QList< QPair< QString, QColor > > &symbolItems SIP_OUT ) const { Q_UNUSED( symbolItems ); } diff --git a/src/core/raster/qgsrastertransparency.cpp b/src/core/raster/qgsrastertransparency.cpp index 61c7b4d09fe8..984967b124b3 100644 --- a/src/core/raster/qgsrastertransparency.cpp +++ b/src/core/raster/qgsrastertransparency.cpp @@ -24,25 +24,16 @@ email : ersts@amnh.org #include #include -/** - Accessor for transparentSingleValuePixelList -*/ QList QgsRasterTransparency::transparentSingleValuePixelList() const { return mTransparentSingleValuePixelList; } -/** - Accessor for transparentThreeValuePixelList -*/ QList QgsRasterTransparency::transparentThreeValuePixelList() const { return mTransparentThreeValuePixelList; } -/** - Reset to the transparency list to a single value -*/ void QgsRasterTransparency::initializeTransparentPixelList( double value ) { //clear the existing list @@ -56,9 +47,6 @@ void QgsRasterTransparency::initializeTransparentPixelList( double value ) mTransparentSingleValuePixelList.append( myTransparentSingleValuePixel ); } -/** - Reset to the transparency list to a single value -*/ void QgsRasterTransparency::initializeTransparentPixelList( double redValue, double greenValue, double blueValue ) { //clearn the existing list @@ -73,29 +61,16 @@ void QgsRasterTransparency::initializeTransparentPixelList( double redValue, dou mTransparentThreeValuePixelList.append( myTransparentThreeValuePixel ); } - -/** - Mutator for transparentSingleValuePixelList, replaces the whole list -*/ void QgsRasterTransparency::setTransparentSingleValuePixelList( const QList &newList ) { mTransparentSingleValuePixelList = newList; } -/** - Mutator for transparentThreeValuePixelList, replaces the whole list -*/ void QgsRasterTransparency::setTransparentThreeValuePixelList( const QList &newList ) { mTransparentThreeValuePixelList = newList; } -/** - Searches through the transparency list, if a match is found, the global transparency value is scaled - by the stored transparency value. - \param value the needle to search for in the transparency hay stack - \param globalTransparency the overal transparency level for the layer -*/ int QgsRasterTransparency::alphaValue( double value, int globalTransparency ) const { //if NaN return 0, transparent @@ -128,14 +103,6 @@ int QgsRasterTransparency::alphaValue( double value, int globalTransparency ) co return globalTransparency; } -/** - Searches through the transparency list, if a match is found, the global transparency value is scaled - by the stored transparency value. - \param redValue the red portion of the needle to search for in the transparency hay stack - \param greenValue the green portion of the needle to search for in the transparency hay stack - \param blueValue the green portion of the needle to search for in the transparency hay stack - \param globalTransparency the overal transparency level for the layer -*/ int QgsRasterTransparency::alphaValue( double redValue, double greenValue, double blueValue, int globalTransparency ) const { //if NaN return 0, transparent diff --git a/src/core/raster/qgsrastertransparency.h b/src/core/raster/qgsrastertransparency.h index 2f4ae7bea0d8..20957503eca4 100644 --- a/src/core/raster/qgsrastertransparency.h +++ b/src/core/raster/qgsrastertransparency.h @@ -66,23 +66,46 @@ class CORE_EXPORT QgsRasterTransparency //! \brief Accessor for transparentThreeValuePixelList QList transparentThreeValuePixelList() const; - //! \brief Reset to the transparency list to a single value - void initializeTransparentPixelList( double ); + /** + * Resets the transparency list to a single \a value. + */ + void initializeTransparentPixelList( double value ); - //! \brief Reset to the transparency list to a single value - void initializeTransparentPixelList( double, double, double ); + /** + * Resets the transparency list to single red, green, and blue values. + */ + void initializeTransparentPixelList( double redValue, double greenValue, double blueValue ); - //! \brief Mutator for transparentSingleValuePixelList + //! \brief Mutator for transparentSingleValuePixelList, replaces the whole list void setTransparentSingleValuePixelList( const QList &newList SIP_TRANSFER ); - //! \brief Mutator for transparentThreeValuePixelList + //! \brief Mutator for transparentThreeValuePixelList, replaces the whole list void setTransparentThreeValuePixelList( const QList &newList SIP_TRANSFER ); - //! \brief Returns the transparency value for a single value Pixel - int alphaValue( double, int globalTransparency = 255 ) const; + /** + * Returns the transparency value for a single \a value pixel. + * + * Searches through the transparency list, and if a match is found, the global transparency value is scaled + * by the stored transparency value. + * + * \param value the needle to search for in the transparency hay stack + * \param globalTransparency the overal transparency level for the layer + */ + int alphaValue( double value, int globalTransparency = 255 ) const; + + //! \brief - //! \brief Return the transparency value for a RGB Pixel - int alphaValue( double, double, double, int globalTransparency = 255 ) const; + /** + * Returns the transparency value for a RGB pixel. + * + * Searches through the transparency list, if a match is found, the global transparency value is scaled + * by the stored transparency value. + * \param redValue the red portion of the needle to search for in the transparency hay stack + * \param greenValue the green portion of the needle to search for in the transparency hay stack + * \param blueValue the green portion of the needle to search for in the transparency hay stack + * \param globalTransparency the overal transparency level for the layer + */ + int alphaValue( double redValue, double greenValue, double blueValue, int globalTransparency = 255 ) const; //! True if there are no entries in the pixel lists except the nodata value bool isEmpty() const; diff --git a/src/gui/qgisinterface.h b/src/gui/qgisinterface.h index 61284b892174..b480221a5f5e 100644 --- a/src/gui/qgisinterface.h +++ b/src/gui/qgisinterface.h @@ -688,7 +688,7 @@ class GUI_EXPORT QgisInterface : public QObject * \see registerCustomLayoutDropHandler() */ virtual void unregisterCustomLayoutDropHandler( QgsLayoutCustomDropHandler *handler ) = 0; - // \todo is this deprecated in favour of QgsContextHelp? + // TODO is this deprecated in favour of QgsContextHelp? /** * Open a url in the users browser. By default the QGIS doc directory is used diff --git a/src/gui/qgsattributeeditorcontext.h b/src/gui/qgsattributeeditorcontext.h index bc172ef48725..8bbc7c5869c4 100644 --- a/src/gui/qgsattributeeditorcontext.h +++ b/src/gui/qgsattributeeditorcontext.h @@ -81,9 +81,8 @@ class GUI_EXPORT QgsAttributeEditorContext } /** - * Sets distance area object for area/length calculations - * \param distanceArea map canvas - * \see setDistanceArea + * Sets distance area object, \a distanceArea, for area/length calculations + * \see distanceArea() * \since QGIS 2.2 */ inline void setDistanceArea( const QgsDistanceArea &distanceArea ) @@ -95,24 +94,41 @@ class GUI_EXPORT QgsAttributeEditorContext } } + /** + * Returns the distance area object used for area/length calculations. + * \see setDistanceArea() + * \since QGIS 2.2 + */ inline const QgsDistanceArea &distanceArea() const { return mDistanceArea; } /** - * Sets the map canvas (e.g. to zoom to related features) - * \param mapCanvas map canvas + * Sets the associated map canvas, \a mapCanvas, (e.g. to zoom to related features). * \see mapCanvas() * \since QGIS 3.2 */ inline void setMapCanvas( QgsMapCanvas *mapCanvas ) { mMapCanvas = mapCanvas; } + + /** + * Returns the associated map canvas (e.g. to zoom to related features). + * \see setMapCanvas() + * \since QGIS 3.2 + */ inline QgsMapCanvas *mapCanvas() const { return mMapCanvas; } /** - * Sets the vector layer tools + * Sets the associated vector layer tools. * \param vlTools vector layer tools * \see vectorLayerTools() * \since QGIS 2.2 */ inline void setVectorLayerTools( QgsVectorLayerTools *vlTools ) { mVectorLayerTools = vlTools; } + // TODO QGIS 4.0 - rename vlTools to tools + + /** + * Returns the associated vector layer tools. + * \see setVectorLayerTools() + * \since QGIS 2.2 + */ inline const QgsVectorLayerTools *vectorLayerTools() const { return mVectorLayerTools; } /** @@ -124,7 +140,21 @@ class GUI_EXPORT QgsAttributeEditorContext * \since QGIS 2.6 */ inline void setRelation( const QgsRelation &relation, RelationMode mode ) { mRelation = relation; mRelationMode = mode; } + + /** + * Returns the attribute relation. + * \see setRelation() + * \see relationMode() + * \since QGIS 2.6 + */ inline const QgsRelation &relation() const { return mRelation; } + + /** + * Returns the attribute relation mode. + * \see setRelation() + * \see relation() + * \since QGIS 2.6 + */ inline RelationMode relationMode() const { return mRelationMode; } /** diff --git a/src/gui/qgsdetaileditemdelegate.cpp b/src/gui/qgsdetaileditemdelegate.cpp index 6e88b4d4fe70..9c332e01fe8a 100644 --- a/src/gui/qgsdetaileditemdelegate.cpp +++ b/src/gui/qgsdetaileditemdelegate.cpp @@ -351,7 +351,7 @@ QStringList QgsDetailedItemDelegate::wordWrap( const QString &string, if ( metrics.width( myCumulativeLine ) >= width ) { //time to wrap - //\todo deal with long strings that have no spaces + //TODO deal with long strings that have no spaces //forcing a break at current pos... myList << myStringToPreviousSpace.trimmed(); i = myPreviousSpacePos; diff --git a/src/gui/qgspropertyassistantwidget.cpp b/src/gui/qgspropertyassistantwidget.cpp index a3eee7f18304..b70e08971e89 100644 --- a/src/gui/qgspropertyassistantwidget.cpp +++ b/src/gui/qgspropertyassistantwidget.cpp @@ -234,7 +234,7 @@ void QgsPropertyAssistantWidget::updatePreview() i++; } // center icon and align text left by giving icons the same width - // \todo maybe add some space so that icons don't touch + // TODO maybe add some space so that icons don't touch for ( int i = 0; i < breaks.length(); i++ ) { QPixmap img( mPreviewList.item( i )->icon().pixmap( mPreviewList.item( i )->icon().actualSize( QSize( 512, 512 ) ) ) ); diff --git a/src/plugins/compass/qgscompassplugin.cpp b/src/plugins/compass/qgscompassplugin.cpp index e83f6dfbc1d3..2ccafe0fb407 100644 --- a/src/plugins/compass/qgscompassplugin.cpp +++ b/src/plugins/compass/qgscompassplugin.cpp @@ -39,12 +39,6 @@ static const QString sPluginVersion = QObject::tr( "Version 0.9" ); static const QgisPlugin::PLUGINTYPE sPluginType = QgisPlugin::UI; static const QString sPluginIcon = ":/compass.svn"; -/** - * 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 - */ QgsCompassPlugin::QgsCompassPlugin( QgisInterface *themQGisIface ) : QgisPlugin( sName, sDescription, sCategory, sPluginVersion, sPluginType ) , mQGisIface( themQGisIface ) diff --git a/src/plugins/compass/qgscompassplugin.h b/src/plugins/compass/qgscompassplugin.h index 51ec3b5e6584..9f32b29ee5b8 100644 --- a/src/plugins/compass/qgscompassplugin.h +++ b/src/plugins/compass/qgscompassplugin.h @@ -36,9 +36,9 @@ class QgsCompassPlugin: public QObject, public QgisPlugin, private Ui::QgsCompas /** * Constructor for a plugin. The QgisInterface pointer is passed by * QGIS when it attempts to instantiate the plugin. - * \param qI Pointer to the QgisInterface object + * \param interface pointer to the QgisInterface object */ - explicit QgsCompassPlugin( QgisInterface * ); + explicit QgsCompassPlugin( QgisInterface *interface ); /** * Virtual function to return the name of the plugin. The name will be used when presenting a list diff --git a/src/plugins/coordinate_capture/coordinatecapture.cpp b/src/plugins/coordinate_capture/coordinatecapture.cpp index a64af3fe9554..c34d9854e03b 100644 --- a/src/plugins/coordinate_capture/coordinatecapture.cpp +++ b/src/plugins/coordinate_capture/coordinatecapture.cpp @@ -58,11 +58,7 @@ static const QgisPlugin::PluginType sPluginType = QgisPlugin::UI; // ////////////////////////////////////////////////////////////////////// -/** - * Constructor for the plugin. The plugin is passed a pointer - * an interface object that provides access to exposed functions in QGIS. - * \param theQGisInterface - Pointer to the QGIS interface object - */ + CoordinateCapture::CoordinateCapture( QgisInterface *qgisInterface ) : QgisPlugin( sName, sDescription, sCategory, sPluginVersion, sPluginType ) , mCanvasDisplayPrecision( 5 ) diff --git a/src/plugins/georeferencer/qgsgeorefplugin.cpp b/src/plugins/georeferencer/qgsgeorefplugin.cpp index 381506617680..32d2585e7f54 100644 --- a/src/plugins/georeferencer/qgsgeorefplugin.cpp +++ b/src/plugins/georeferencer/qgsgeorefplugin.cpp @@ -72,12 +72,6 @@ static const QString sPluginIcon = QStringLiteral( ":/icons/default/mGeorefRun.p // ////////////////////////////////////////////////////////////////////// -/** - * 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 theQGisApp - Pointer to the QGIS main window - * \param theQGisInterface - Pointer to the QGIS interface object - */ QgsGeorefPlugin::QgsGeorefPlugin( QgisInterface *qgisInterface ) : QgisPlugin( sName, sDescription, sCategory, sPluginVersion, sPluginType ) , mQGisIface( qgisInterface ) diff --git a/src/plugins/georeferencer/qgsgeorefplugin.h b/src/plugins/georeferencer/qgsgeorefplugin.h index 7fb8eb626e48..fcae0424c1af 100644 --- a/src/plugins/georeferencer/qgsgeorefplugin.h +++ b/src/plugins/georeferencer/qgsgeorefplugin.h @@ -71,10 +71,9 @@ class QgsGeorefPlugin: public QObject, public QgisPlugin /** * Constructor for a plugin. The QgisApp and QgisIface pointers are passed by * QGIS when it attempts to instantiate the plugin. - * \param Pointer to the QgisApp object - * \param Pointer to the QgisIface object. + * \param interface pointer to the QgisIface object. */ - explicit QgsGeorefPlugin( QgisInterface * ); + explicit QgsGeorefPlugin( QgisInterface *interface ); public slots: //! init the gui diff --git a/src/plugins/gps_importer/qgsgpsplugin.cpp b/src/plugins/gps_importer/qgsgpsplugin.cpp index acead25f6b48..c4fd10961da6 100644 --- a/src/plugins/gps_importer/qgsgpsplugin.cpp +++ b/src/plugins/gps_importer/qgsgpsplugin.cpp @@ -55,13 +55,6 @@ static const QString version_ = QObject::tr( "Version 0.1" ); static const QgisPlugin::PluginType type_ = QgisPlugin::UI; static const QString icon_ = QStringLiteral( ":/gps_importer.svg" ); - -/** - * 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 - */ QgsGpsPlugin::QgsGpsPlugin( QgisInterface *qgisInterFace ) : QgisPlugin( name_, description_, category_, version_, type_ ) , mQGisInterface( qgisInterFace ) diff --git a/src/plugins/gps_importer/qgsgpsplugin.h b/src/plugins/gps_importer/qgsgpsplugin.h index 02a691d2cf2b..2b1030b9cc54 100644 --- a/src/plugins/gps_importer/qgsgpsplugin.h +++ b/src/plugins/gps_importer/qgsgpsplugin.h @@ -39,7 +39,7 @@ class QgsGpsPlugin: public QObject, public QgisPlugin /** * Constructor for a plugin. The QgisInterface pointer * is passed by QGIS when it attempts to instantiate the plugin. - * \param qI Pointer to the QgisInterface object. + * \param interface pointer to the QgisInterface object. */ explicit QgsGpsPlugin( QgisInterface * ); diff --git a/src/server/qgsserver.cpp b/src/server/qgsserver.cpp index 3da12866f6f2..ea6ffb591b07 100644 --- a/src/server/qgsserver.cpp +++ b/src/server/qgsserver.cpp @@ -88,10 +88,6 @@ QFileInfo QgsServer::defaultAdminSLD() return QFileInfo( QStringLiteral( "admin.sld" ) ); } - -/** - * \brief QgsServer::setupNetworkAccessManager - */ void QgsServer::setupNetworkAccessManager() { QSettings settings; @@ -106,10 +102,6 @@ void QgsServer::setupNetworkAccessManager() nam->setCache( cache ); } -/** - * \brief QgsServer::defaultProjectFile - * \return the default project file - */ QFileInfo QgsServer::defaultProjectFile() { QDir currentDir; @@ -128,11 +120,6 @@ QFileInfo QgsServer::defaultProjectFile() return projectFiles.at( 0 ); } -/** - * \brief QgsServer::printRequestParameters prints the request parameters - * \param parameterMap - * \param logLevel - */ void QgsServer::printRequestParameters( const QMap< QString, QString> ¶meterMap, Qgis::MessageLevel logLevel ) { if ( logLevel > Qgis::Info ) @@ -147,12 +134,6 @@ void QgsServer::printRequestParameters( const QMap< QString, QString> ¶meter } } -/** - * \brief QgsServer::configPath - * \param defaultConfigPath - * \param parameters - * \return config file path - */ QString QgsServer::configPath( const QString &defaultConfigPath, const QMap ¶meters ) { QString cfPath( defaultConfigPath ); @@ -178,10 +159,6 @@ QString QgsServer::configPath( const QString &defaultConfigPath, const QMaplogLevel(); diff --git a/src/server/qgsserver.h b/src/server/qgsserver.h index 60f0fa72fc6f..2952ab0f2cad 100644 --- a/src/server/qgsserver.h +++ b/src/server/qgsserver.h @@ -103,8 +103,9 @@ class SERVER_EXPORT QgsServer //! Server initialization static bool init(); - // All functions that where previously in the main file are now - // static methods of this class + /** + * Returns the configuration file path. + */ static QString configPath( const QString &defaultConfigPath, const QMap ¶meters ); @@ -117,9 +118,17 @@ class SERVER_EXPORT QgsServer const QMap< QString, QString> ¶meterMap, Qgis::MessageLevel logLevel ); + /** + * Returns the default project file. + */ static QFileInfo defaultProjectFile(); static QFileInfo defaultAdminSLD(); + + /** + * \brief QgsServer::setupNetworkAccessManager + */ static void setupNetworkAccessManager(); + //! Create and return a request handler instance static QgsRequestHandler *createRequestHandler( const QgsServerRequest &request, QgsServerResponse &response ); diff --git a/tests/code_layout/acceptable_missing_doc.py b/tests/code_layout/acceptable_missing_doc.py index 308cfb6932db..2d79d6c4aaea 100644 --- a/tests/code_layout/acceptable_missing_doc.py +++ b/tests/code_layout/acceptable_missing_doc.py @@ -1537,7 +1537,20 @@ "QgsRuleBasedLabeling::Rule", "QgsActionMenu", "QgsAuthMethod", - "QgsDartMeasurement"] + "QgsDartMeasurement", + "QgsExpressionNode::NodeList", + "QgsExpressionFunction", + "QgsExpressionNode", + "QgsExpressionNodeBinaryOperator", + "QgsExpressionNodeColumnRef", + "QgsExpressionNodeCondition", + "QgsExpressionNodeFunction", + "QgsExpressionNodeInOperator", + "QgsExpressionNodeLiteral", + "QgsExpressionNodeUnaryOperator", + "QgsStaticExpressionFunction", + "QgsExpressionNodeCondition::WhenThen" +] ACCEPTABLE_MISSING_BRIEF = ['QgsBrushStyleComboBox', 'QgsHiddenWidgetFactory',