Skip to content
Permalink
Browse files

Add TRUE and FALSE macros for use in doxygen comments

For the c++ api dox these expand to "\c true" and "\c false" (the
\c directive indicates a code literal value), and for sipify/Python
they expand to ``True`` and ``False`` (`` is sphinx annotation
for literal values)

Makes for nicer dox for both c++ and Python!
  • Loading branch information
nyalldawson committed Feb 26, 2019
1 parent 5aecf74 commit eed9852fb9f850a9d0c3f337a8636fa2f791d4bd
Showing with 115 additions and 107 deletions.
  1. +1 −1 cmake_templates/Doxyfile.in
  2. +48 −48 python/core/auto_generated/qgsvectorlayer.sip.in
  3. +9 −1 scripts/sipify.pl
  4. +57 −57 src/core/qgsvectorlayer.h
@@ -898,7 +898,7 @@ IMAGE_PATH =
# need to set EXTENSION_MAPPING for the extension otherwise the files are not
# properly processed by doxygen.

INPUT_FILTER =
INPUT_FILTER = "sed -e 's/TRUE/\\c true/' -e 's/FALSE/\\c false/'"

# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
# basis. Doxygen will compare the file name with each pattern and apply the
@@ -440,7 +440,7 @@ Joins another vector layer to this layer
%Docstring
Removes a vector layer join

:return: true if join was found and successfully removed
:return: ``True`` if join was found and successfully removed
%End

QgsVectorLayerJoinBuffer *joinBuffer();
@@ -460,7 +460,7 @@ Sets the list of dependencies.

:param layers: set of :py:class:`QgsMapLayerDependency`. Only user-defined dependencies will be added

:return: false if a dependency cycle has been detected
:return: ``False`` if a dependency cycle has been detected

.. versionadded:: 3.0
%End
@@ -678,7 +678,7 @@ Returns the bounding box of the selected features. If there is no selection, Qgs
%Docstring
Returns whether the layer contains labels which are enabled and should be drawn.

:return: true if layer contains enabled labels
:return: ``True`` if layer contains enabled labels

.. seealso:: :py:func:`setLabelsEnabled`

@@ -691,7 +691,7 @@ Sets whether labels should be ``enabled`` for the layer.

.. note::

Labels will only be rendered if labelsEnabled() is true and a labeling
Labels will only be rendered if labelsEnabled() is ``True`` and a labeling
object is returned by labeling().

.. seealso:: :py:func:`labelsEnabled`
@@ -703,7 +703,7 @@ Sets whether labels should be ``enabled`` for the layer.
%Docstring
Returns whether the layer contains diagrams which are enabled and should be drawn.

:return: true if layer contains enabled diagrams
:return: ``True`` if layer contains enabled diagrams

.. versionadded:: 2.9
%End
@@ -818,7 +818,7 @@ Delete a style from the database

:param styleId: the provider's layer_styles table id of the style to delete

:return: - true in case of success
:return: - ``True`` in case of success
- msgError: reference to string that will be updated with any error messages

.. versionadded:: 3.0
@@ -830,29 +830,29 @@ Delete a style from the database
Load a named style from file/local db/datasource db

:param theURI: the URI of the style or the URI of the layer
:param resultFlag: will be set to true if a named style is correctly loaded
:param loadFromLocalDb: if true forces to load from local db instead of datasource one
:param resultFlag: will be set to ``True`` if a named style is correctly loaded
:param loadFromLocalDb: if ``True`` forces to load from local db instead of datasource one
:param categories: the style categories to be loaded.
%End

virtual QString loadNamedStyle( const QString &theURI, bool &resultFlag /Out/,
QgsMapLayer::StyleCategories categories = QgsMapLayer::AllStyleCategories ) ${SIP_FINAL};
%Docstring
Calls loadNamedStyle( theURI, resultFlag, false );
Calls loadNamedStyle( theURI, resultFlag, ``False`` );
Retained for backward compatibility
%End

bool loadAuxiliaryLayer( const QgsAuxiliaryStorage &storage, const QString &key = QString() );
%Docstring
Loads the auxiliary layer for this vector layer. If there's no
corresponding table in the database, then nothing happens and false is
corresponding table in the database, then nothing happens and ``False`` is
returned. The key is optional because if this layer has been read from
a XML document, then the key read in this document is used by default.

:param storage: The auxiliary storage where to look for the table
:param key: The key to use for joining.

:return: true if the auxiliary layer is well loaded, false otherwise
:return: ``True`` if the auxiliary layer is well loaded, ``False`` otherwise


.. versionadded:: 3.0
@@ -886,7 +886,7 @@ Read the symbology for the current layer from the Dom node supplied.
:param context: reading context (used for transform from relative to absolute paths)
:param categories: the style categories to be read

:return: true in case of success.
:return: ``True`` in case of success.
%End

virtual bool readStyle( const QDomNode &node, QString &errorMessage,
@@ -899,7 +899,7 @@ Read the style for the current layer from the Dom node supplied.
:param context: reading context (used for transform from relative to absolute paths)
:param categories: the style categories to be read

:return: true in case of success.
:return: ``True`` in case of success.
%End

virtual bool writeSymbology( QDomNode &node, QDomDocument &doc, QString &errorMessage,
@@ -913,7 +913,7 @@ Write the symbology for the layer into the docment provided.
:param context: writing context (used for transform from absolute to relative paths)
:param categories: the style categories to be written

:return: true in case of success.
:return: ``True`` in case of success.
%End

virtual bool writeStyle( QDomNode &node, QDomDocument &doc, QString &errorMessage,
@@ -927,7 +927,7 @@ Write just the style information for the layer into the document
:param context: writing context (used for transform from absolute to relative paths)
:param categories: the style categories to be written

:return: true in case of success.
:return: ``True`` in case of success.
%End

bool writeSld( QDomNode &node, QDomDocument &doc, QString &errorMessage, const QgsStringMap &props = QgsStringMap() ) const;
@@ -939,7 +939,7 @@ Writes the symbology of the layer into the document provided in SLD 1.1 format
:param errorMessage: reference to string that will be updated with any error messages
:param props: a open ended set of properties that can drive/inform the SLD encoding

:return: true in case of success
:return: ``True`` in case of success
%End

virtual bool readSld( const QDomNode &node, QString &errorMessage ) ${SIP_FINAL};
@@ -976,7 +976,7 @@ if the geometry type of the new data source matches the current geometry type of
:param dataSource: new layer data source
:param baseName: base name of the layer
:param provider: provider string
:param loadDefaultStyleFlag: set to true to reset the layer's style to the default for the
:param loadDefaultStyleFlag: set to ``True`` to reset the layer's style to the default for the
data source

.. versionadded:: 2.10
@@ -994,7 +994,7 @@ if the geometry type of the new data source matches the current geometry type of
:param baseName: base name of the layer
:param provider: provider string
:param options: provider options
:param loadDefaultStyleFlag: set to true to reset the layer's style to the default for the
:param loadDefaultStyleFlag: set to ``True`` to reset the layer's style to the default for the
data source

.. seealso:: :py:func:`dataSourceChanged`
@@ -1029,7 +1029,7 @@ Set the string (typically sql) used to define a subset of the layer
or other definition string specific to the underlying dataprovider
and data store.

:return: true, when setting the subset string was successful, false otherwise
:return: ``True``, when setting the subset string was successful, ``False`` otherwise
%End

virtual QString subsetString() const;
@@ -1085,10 +1085,10 @@ Updates an existing ``feature`` in the layer, replacing the attributes and geome
with matching QgsFeature.id() with the attributes and geometry from ``feature``.
Changes are not immediately committed to the layer.

If ``skipDefaultValue`` is set to true, default field values will not
If ``skipDefaultValue`` is set to ``True``, default field values will not
be updated. This can be used to override default field value expressions.

Returns true if the feature's attribute was successfully changed.
Returns ``True`` if the feature's attribute was successfully changed.

.. note::

@@ -1195,7 +1195,7 @@ Deletes a vertex from a feature.
%Docstring
Deletes the selected features

:return: true in case of success and false otherwise
:return: ``True`` in case of success and ``False`` otherwise
%End

QgsGeometry::OperationResult addRing( const QVector<QgsPointXY> &ring, QgsFeatureId *featureId = 0 );
@@ -1336,7 +1336,7 @@ Translates feature by dx, dy
Splits parts cut by the given line

:param splitLine: line that splits the layer features
:param topologicalEditing: true if topological editing is enabled
:param topologicalEditing: ``True`` if topological editing is enabled

:return: QgsGeometry.OperationResult
- Success
@@ -1360,7 +1360,7 @@ Splits parts cut by the given line
Splits features cut by the given line

:param splitLine: line that splits the layer features
:param topologicalEditing: true if topological editing is enabled
:param topologicalEditing: ``True`` if topological editing is enabled

:return: QgsGeometry.OperationResult
- Success
@@ -1425,7 +1425,7 @@ Access to labeling configuration. May be null if labeling is not used.

.. note::

Labels will only be rendered if labelsEnabled() returns true.
Labels will only be rendered if labelsEnabled() returns ``True``.

.. seealso:: :py:func:`labelsEnabled`

@@ -1442,24 +1442,24 @@ Set labeling configuration. Takes ownership of the object.
virtual bool isEditable() const ${SIP_FINAL};

%Docstring
Returns true if the provider is in editing mode
Returns ``True`` if the provider is in editing mode
%End

virtual bool isSpatial() const ${SIP_FINAL};

%Docstring
Returns true if this is a geometry layer and false in case of NoGeometry (table only) or UnknownGeometry
Returns ``True`` if this is a geometry layer and ``False`` in case of NoGeometry (table only) or UnknownGeometry
%End

virtual bool isModified() const;
%Docstring
Returns true if the provider has been modified since the last commit
Returns ``True`` if the provider has been modified since the last commit
%End

bool isAuxiliaryField( int index, int &srcIndex ) const;
%Docstring
Returns true if the field comes from the auxiliary layer,
false otherwise.
Returns ``True`` if the field comes from the auxiliary layer,
``False`` otherwise.

.. versionadded:: 3.0
%End
@@ -1515,7 +1515,7 @@ If you need only the count of committed features call this method on this layer'
%Docstring
Make layer read-only (editing disabled) or not

:return: false if the layer is in editing yet
:return: ``False`` if the layer is in editing yet
%End

bool changeGeometry( QgsFeatureId fid, QgsGeometry &geometry, bool skipDefaultValue = false );
@@ -1524,10 +1524,10 @@ Changes a feature's ``geometry`` within the layer's edit buffer
(but does not immediately commit the changes). The ``fid`` argument
specifies the ID of the feature to be changed.

If ``skipDefaultValue`` is set to true, default field values will not
If ``skipDefaultValue`` is set to ``True``, default field values will not
be updated. This can be used to override default field value expressions.

Returns true if the feature's geometry was successfully changed.
Returns ``True`` if the feature's geometry was successfully changed.

.. note::

@@ -1561,10 +1561,10 @@ QVariant is used (the default behavior), then the feature's current value will b
retrieved and used. Note that this involves a feature request to the underlying data provider,
so it is more efficient to explicitly pass an ``oldValue`` if it is already available.

If ``skipDefaultValues`` is set to true, default field values will not
If ``skipDefaultValues`` is set to ``True``, default field values will not
be updated. This can be used to override default field value expressions.

Returns true if the feature's attribute was successfully changed.
Returns ``True`` if the feature's attribute was successfully changed.

.. note::

@@ -1598,11 +1598,11 @@ automatically retrieved and used. Note that this involves a feature
request to the underlying data provider, so it is more efficient to
explicitly pass an oldValue if it is already available.

If ``skipDefaultValues`` is set to true, default field values will not
If ``skipDefaultValues`` is set to ``True``, default field values will not
be updated. This can be used to override default field value
expressions.

Returns true if feature's attributes was successfully changed.
Returns ``True`` if feature's attributes was successfully changed.

.. note::

@@ -1629,7 +1629,7 @@ Returns true if feature's attributes was successfully changed.
bool addAttribute( const QgsField &field );
%Docstring
Add an attribute field (but does not commit it)
returns true if the field was added
returns ``True`` if the field was added

.. note::

@@ -1726,7 +1726,7 @@ Deletes a list of attribute fields (but does not commit it)

:param attrs: the indices of the attributes to delete

:return: true if at least one attribute has been deleted
:return: ``True`` if at least one attribute has been deleted
%End

virtual bool addFeatures( QgsFeatureList &features, QgsFeatureSink::Flags flags = 0 ) ${SIP_FINAL};
@@ -1750,7 +1750,7 @@ Deletes a set of features from the layer (but does not commit it)

:param fids: The feature ids to delete

:return: false if the layer is not in edit mode or does not support deleting
:return: ``False`` if the layer is not in edit mode or does not support deleting
in case of an active transaction depends on the provider implementation

.. note::
@@ -1766,7 +1766,7 @@ Deletes a set of features from the layer (but does not commit it)
Attempts to commit to the underlying data provider any buffered changes made since the
last to call to startEditing().

Returns the result of the attempt. If a commit fails (i.e. false is returned), the
Returns the result of the attempt. If a commit fails (i.e. ``False`` is returned), the
in-memory changes are left untouched and are not discarded. This allows editing to
continue if the commit failed on e.g. a disallowed value in a Postgres
database - the user can re-edit and try again.
@@ -1797,7 +1797,7 @@ to commit changes to the layer.
%Docstring
Stops a current editing operation and discards any uncommitted edits.

If ``deleteBuffer`` is true the editing buffer will be completely deleted (the default
If ``deleteBuffer`` is ``True`` the editing buffer will be completely deleted (the default
behavior).

.. seealso:: :py:func:`startEditing`
@@ -2088,7 +2088,7 @@ Calculates an aggregated value from the layer's features.
:param fieldOrExpression: source field or expression to use as basis for aggregated values.
:param parameters: parameters controlling aggregate calculation
:param context: expression context for expressions and filters
:param ok: if specified, will be set to true if aggregate calculation was successful
:param ok: if specified, will be set to ``True`` if aggregate calculation was successful

:return: calculated aggregate value

@@ -2232,8 +2232,8 @@ to determine it.

bool readExtentFromXml() const;
%Docstring
Returns true if the extent is read from the XML document when data
source has no metadata, false if it's the data provider which determines
Returns ``True`` if the extent is read from the XML document when data
source has no metadata, ``False`` if it's the data provider which determines
it.

.. versionadded:: 3.0
@@ -2305,7 +2305,7 @@ Clear selection
Update the extents for the layer. This is necessary if features are
added/deleted or the layer has been subsetted.

:param force: true to update layer extent even if it's read from xml by default, false otherwise
:param force: ``True`` to update layer extent even if it's read from xml by default, ``False`` otherwise
%End

bool startEditing();
@@ -2316,7 +2316,7 @@ This starts an edit session on this layer. Changes made in this edit session wil
be made persistent until commitChanges() is called, and can be reverted by calling
rollBack().

Returns true if the layer was successfully made editable, or false if the operation
Returns ``True`` if the layer was successfully made editable, or ``False`` if the operation
failed (e.g. due to an underlying read-only data source, or lack of edit support
by the backend data provider).

@@ -2333,7 +2333,7 @@ Emitted when selection was changed

:param selected: Newly selected feature ids
:param deselected: Ids of all features which have previously been selected but are not any more
:param clearAndSelect: In case this is set to true, the old selection was dismissed and the new selection corresponds to selected
:param clearAndSelect: In case this is set to ``True``, the old selection was dismissed and the new selection corresponds to selected
%End

void layerModified();

0 comments on commit eed9852

Please sign in to comment.
You can’t perform that action at this time.