Better approach to avoid duplicate docs

qgis · Jun 10, 2021 · 49e48f9 · 49e48f9
1 parent 4ff3f44
commit 49e48f9
Show file tree

Hide file tree

Showing 11 changed files with 260 additions and 240 deletions.
diff --git a/python/core/auto_generated/qgsfeature.sip.in b/python/core/auto_generated/qgsfeature.sip.in
@@ -15,7 +15,7 @@
 class QgsFeature
 {
 %Docstring(signature="appended")
-The feature class encapsulates a single feature including its id,
+The feature class encapsulates a single feature including its unique ID,
 geometry and a list of field/values attributes.
 
 .. note::
@@ -139,15 +139,15 @@ geometry and a list of field/values attributes.
 %Docstring
 Constructor for QgsFeature
 
-:param id: feature id
+:param id: unique feature ID
 %End
 
     QgsFeature( const QgsFields &fields, qint64 id = FID_NULL );
 %Docstring
 Constructor for QgsFeature
 
 :param fields: feature's fields
-:param id: feature id
+:param id: unique feature ID
 %End
 
     QgsFeature( const QgsFeature &rhs );
@@ -162,16 +162,14 @@ Copy constructor
 
     QgsFeatureId id() const;
 %Docstring
-Gets the feature ID for this feature.
-
-:return: feature ID
+Returns the feature ID for this feature.
 
 .. seealso:: :py:func:`setId`
 %End
 
     void setId( QgsFeatureId id );
 %Docstring
-Sets the feature ID for this feature.
+Sets the feature ``id`` for this feature.
 
 :param id: feature id
 
@@ -182,8 +180,6 @@ Sets the feature ID for this feature.
 %Docstring
 Returns the feature's attributes.
 
-:return: list of feature's attributes
-
 .. seealso:: :py:func:`setAttributes`
 
 .. note::
@@ -203,27 +199,30 @@ Returns the number of attributes attached to the feature.
     void setAttributes( const QgsAttributes &attrs );
 %Docstring
 Sets the feature's attributes.
-The feature will be valid after. The number of provided attributes need to match exactly the
-number of the feature's fields.
 
-:param attrs: List of attribute values
+Calling this method will automatically set the feature as valid (see :py:func:`~QgsFeature.isValid`).
 
-.. seealso:: :py:func:`setAttribute`
+The number of provided attributes need to exactly match the number of the feature's fields.
 
-.. seealso:: :py:func:`attributes`
+:param attrs: List of attribute values
 
 .. warning::
 
-   Method will return false if the number of provided attributes does not exactly match
-   the number of the feature's fields and it will not be possible to add this feature to the data
+   If the number of provided attributes does not exactly match
+   the number of the feature's fields then it will not be possible to add this feature to the corresponding data
    provider.
-%End
 
 
+.. seealso:: :py:func:`setAttribute`
+
+.. seealso:: :py:func:`attributes`
+%End
+
     bool setAttribute( int field, const QVariant &attr /GetWrapper/ );
 %Docstring
-Set an attribute's value by field index.
-The feature will be valid if it was successful.
+Sets an attribute's value by field index.
+
+If the attribute was successfully set then the feature will be automatically marked as valid (see :py:func:`~QgsFeature.isValid`).
 
 :param field: the index of the field to set
 :param attr: the value of the attribute
@@ -259,7 +258,9 @@ The feature will be valid if it was successful.
 
     void initAttributes( int fieldCount );
 %Docstring
-Initialize this feature with the given number of fields. Discard any previously set attribute data.
+Initialize this feature with the given number of fields.
+
+Discards any previously set attribute data.
 
 :param fieldCount: Number of fields to initialize
 
@@ -292,20 +293,19 @@ Resizes the attributes attached to this feature by appending the specified ``cou
 .. versionadded:: 3.18
 %End
 
-
     void deleteAttribute( int field );
 %Docstring
 Deletes an attribute and its value.
 
 :param field: the index of the field
 
-.. seealso:: :py:func:`setAttribute`
-
 :raises `KeyError` if the field is not found
 
 .. note::
 
    Alternatively in Python: @code del feature[field] @endcode
+
+.. seealso:: :py:func:`setAttribute`
 %End
 %MethodCode
     if ( a0 >= 0 && a0 < sipCpp->attributes().count() )
@@ -319,8 +319,9 @@ Deletes an attribute and its value.
 
     bool isValid() const;
 %Docstring
-Returns the validity of this feature. This is normally set by
-the provider to indicate some problem that makes the feature
+Returns the validity of this feature.
+
+This is normally set by the provider to indicate some problem that makes the feature
 invalid or to indicate a null feature.
 
 .. seealso:: :py:func:`setValid`
@@ -356,7 +357,9 @@ an empty :py:class:`QgsGeometry` object will be returned.
 
     void setGeometry( const QgsGeometry &geometry );
 %Docstring
-Set the feature's geometry. The feature will be valid after.
+Set the feature's geometry.
+
+Calling this method will automatically set the feature as valid (see :py:func:`~QgsFeature.isValid`).
 
 :param geometry: new feature geometry
 
@@ -367,8 +370,11 @@ Set the feature's geometry. The feature will be valid after.
 
     void setGeometry( QgsAbstractGeometry *geometry /Transfer/ );
 %Docstring
-Set the feature's ``geometry``. Ownership of the geometry is transferred to the feature.
-The feature will be made valid after calling this method.
+Set the feature's ``geometry``.
+
+Ownership of the geometry is transferred to the feature.
+
+Calling this method will automatically set the feature as valid (see :py:func:`~QgsFeature.isValid`).
 
 This method is a shortcut for calling:
 
@@ -416,12 +422,10 @@ Removes any geometry associated with the feature.
 
     void setFields( const QgsFields &fields, bool initAttributes = true  );
 %Docstring
-Assign a field map with the feature to allow attribute access by attribute name.
+Assigns a field map with the feature to allow attribute access by attribute name.
 
 :param fields: The attribute fields which this feature holds
 :param initAttributes: If ``True``, attributes are initialized. Clears any data previously assigned.
-                       C++: Defaults to ``False``
-                       Python: Defaults to ``True``
 
 .. seealso:: :py:func:`fields`
 
@@ -435,12 +439,15 @@ Returns the field map associated with the feature.
 .. seealso:: :py:func:`setFields`
 %End
 
-
     void setAttribute( const QString &name, const QVariant &value /GetWrapper/ );
 %Docstring
-Insert a value into attribute. Returns ``False`` if attribute name could not be converted to index.
+Insert a value into attribute, by field ``name``.
+
+Returns ``False`` if field ``name`` could not be matched.
+
 Field map must be associated using :py:func:`~QgsFeature.setFields` before this method can be used.
-The feature will be valid if it was successful
+
+Calling this method will automatically set the feature as valid (see :py:func:`~QgsFeature.isValid`).
 
 :param name: The name of the field to set
 :param value: The value to set
@@ -476,8 +483,9 @@ The feature will be valid if it was successful
 
     bool deleteAttribute( const QString &name );
 %Docstring
-Removes an attribute value by field name. Field map must be associated using :py:func:`~QgsFeature.setFields`
-before this method can be used.
+Removes an attribute value by field ``name``.
+
+Field map must be associated using setFields()before this method can be used.
 
 :param name: The name of the field to delete
 
@@ -504,14 +512,16 @@ before this method can be used.
     }
 %End
 
-
     SIP_PYOBJECT attribute( const QString &name ) const;
 %Docstring
-Lookup attribute value from attribute name. Field map must be associated using :py:func:`~QgsFeature.setFields`
-before this method can be used.
+Lookup attribute value by attribute ``name``.
+
+Field map must be associated using :py:func:`~QgsFeature.setFields` before this method can be used.
 
 :param name: The name of the attribute to get
 
+:return: The value of the attribute
+
 :raises `KeyError` if the field is not found
 
 .. note::
@@ -537,11 +547,14 @@ before this method can be used.
 
     SIP_PYOBJECT attribute( int fieldIdx ) const;
 %Docstring
-Lookup attribute value from its index. Field map must be associated using :py:func:`~QgsFeature.setFields`
-before this method can be used.
+Lookup attribute value from its index.
+
+Field map must be associated using :py:func:`~QgsFeature.setFields` before this method can be used.
 
 :param fieldIdx: The index of the attribute to get
 
+:return: The value of the attribute
+
 :raises `KeyError` if the field is not found
 
 .. note::
@@ -583,8 +596,9 @@ Ownership of ``symbol`` is transferred to the feature.
 
     int fieldNameIndex( const QString &fieldName ) const;
 %Docstring
-Utility method to get attribute index from name. Field map must be associated using :py:func:`~QgsFeature.setFields`
-before this method can be used.
+Utility method to get attribute index from name.
+
+Field map must be associated using :py:func:`~QgsFeature.setFields` before this method can be used.
 
 :param fieldName: name of field to get attribute index of
 

diff --git a/python/core/auto_generated/qgsfields.sip.in b/python/core/auto_generated/qgsfields.sip.in
@@ -151,7 +151,6 @@ Returns if a field index is valid
       sipRes = new QgsField( sipCpp->operator[]( idx ) );
 %End
 
-
     QgsField at( int i ) const /Factory/;
 %Docstring
 Returns the field at particular index (must be in range 0..N-1).
@@ -170,7 +169,6 @@ Returns the field at particular index (must be in range 0..N-1).
     }
 %End
 
-
     QgsField field( int fieldIdx ) const /Factory/;
 %Docstring
 Returns the field at particular index (must be in range 0..N-1).
@@ -209,7 +207,6 @@ Returns the field with matching name.
     }
 %End
 
-
     FieldOrigin fieldOrigin( int fieldIdx ) const;
 %Docstring
 Returns the field's origin (value from an enumeration).
@@ -228,7 +225,6 @@ Returns the field's origin (value from an enumeration).
     }
 %End
 
-
     int fieldOriginIndex( int fieldIdx ) const;
 %Docstring
 Returns the field's origin index (its meaning is specific to each type of origin).
@@ -250,8 +246,10 @@ Returns the field's origin index (its meaning is specific to each type of origin
     int indexFromName( const QString &fieldName ) const;
 %Docstring
 Gets the field index from the field name.
+
 This method is case sensitive and only matches the data source
 name of the field.
+
 Alias for indexOf
 
 :param fieldName: The name of the field.
@@ -264,6 +262,7 @@ Alias for indexOf
     int indexOf( const QString &fieldName ) const;
 %Docstring
 Gets the field index from the field name.
+
 This method is case sensitive and only matches the data source
 name of the field.
 
@@ -309,7 +308,6 @@ Utility function to return a list of :py:class:`QgsField` instances
     bool operator==( const QgsFields &other ) const;
     bool operator!=( const QgsFields &other ) const;
 
-
     QIcon iconForField( int fieldIdx, bool considerOrigin = false ) const /Factory/;
 %Docstring
 Returns an icon corresponding to a field index, based on the field's type and source
@@ -333,7 +331,6 @@ Returns an icon corresponding to a field index, based on the field's type and so
     }
 %End
 
-
     static QIcon iconForFieldType( const QVariant::Type &type ) /Factory/;
 %Docstring
 Returns an icon corresponding to a field ``type``

diff --git a/python/core/auto_generated/textrenderer/qgstextblock.sip.in b/python/core/auto_generated/textrenderer/qgstextblock.sip.in
@@ -76,7 +76,6 @@ Applies a ``capitalization`` style to the block's text.
     sipRes = sipCpp->size();
 %End
 
-
     const QgsTextFragment &at( int index ) const /Factory/;
 %Docstring
 Returns the fragment at the specified ``index``.

diff --git a/python/core/auto_generated/textrenderer/qgstextdocument.sip.in b/python/core/auto_generated/textrenderer/qgstextdocument.sip.in
@@ -62,7 +62,6 @@ Appends a ``block`` to the document.
 Reserves the specified ``count`` of blocks for optimised block appending.
 %End
 
-
     const QgsTextBlock &at( int index ) const /Factory/;
 %Docstring
 Returns the block at the specified ``index``.

diff --git a/scripts/astyle_all.sh b/scripts/astyle_all.sh
@@ -34,7 +34,7 @@ find python src tests -type f -print | while read -r f; do
         fi
 
 	echo -ne "Reformatting $f $elcr"
-	astyle.sh "$f" || true
+	astyle.sh "$f" || true &
 done
 
 remove_temporary_files.sh

diff --git a/scripts/doxygen_space.pl b/scripts/doxygen_space.pl
@@ -49,7 +49,10 @@
     my $new_line = $INPUT_LINES[$LINE_IDX];
     my $is_blank_line = ( $new_line =~ m/^\s*$/ ) ? 1 : 0;
 
-    if ( $new_line =~ m/^(\s*)\/\/!\s*(.*?)$/ ){
+    if ( $new_line =~ m/^(\s*)(?:#ifdef|#ifndef|#else|#endif)/ ){
+      print $out_handle $new_line."\n";
+    }
+    elsif ( $new_line =~ m/^(\s*)\/\/!\s*(.*?)$/ ){
        #found a //! comment
        my $indentation = $1;
        my $comment = $2;
@@ -134,7 +137,7 @@
           $BUFFERED_LINE = "";
         }
 
-        if ($new_line !~ m/^\s*\*/ && $new_line =~ m/^(\s*?)(\s?)(.+?)$/ )
+        if ($new_line !~ m/^\s*[#\*]/ && $new_line =~ m/^(\s*?)(\s?)(.+?)$/ )
         {
           $new_line = "$1* $3";
         }