Skip to content

Commit eed9852

Browse files
committed
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!
1 parent 5aecf74 commit eed9852

File tree

4 files changed

+115
-107
lines changed

4 files changed

+115
-107
lines changed

cmake_templates/Doxyfile.in

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -898,7 +898,7 @@ IMAGE_PATH =
898898
# need to set EXTENSION_MAPPING for the extension otherwise the files are not
899899
# properly processed by doxygen.
900900

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

903903
# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
904904
# basis. Doxygen will compare the file name with each pattern and apply the

python/core/auto_generated/qgsvectorlayer.sip.in

Lines changed: 48 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -440,7 +440,7 @@ Joins another vector layer to this layer
440440
%Docstring
441441
Removes a vector layer join
442442

443-
:return: true if join was found and successfully removed
443+
:return: ``True`` if join was found and successfully removed
444444
%End
445445

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

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

463-
:return: false if a dependency cycle has been detected
463+
:return: ``False`` if a dependency cycle has been detected
464464

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

681-
:return: true if layer contains enabled labels
681+
:return: ``True`` if layer contains enabled labels
682682

683683
.. seealso:: :py:func:`setLabelsEnabled`
684684

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

692692
.. note::
693693

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

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

706-
:return: true if layer contains enabled diagrams
706+
:return: ``True`` if layer contains enabled diagrams
707707

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

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

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

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

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

838838
virtual QString loadNamedStyle( const QString &theURI, bool &resultFlag /Out/,
839839
QgsMapLayer::StyleCategories categories = QgsMapLayer::AllStyleCategories ) ${SIP_FINAL};
840840
%Docstring
841-
Calls loadNamedStyle( theURI, resultFlag, false );
841+
Calls loadNamedStyle( theURI, resultFlag, ``False`` );
842842
Retained for backward compatibility
843843
%End
844844

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

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

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

857857

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

889-
:return: true in case of success.
889+
:return: ``True`` in case of success.
890890
%End
891891

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

902-
:return: true in case of success.
902+
:return: ``True`` in case of success.
903903
%End
904904

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

916-
:return: true in case of success.
916+
:return: ``True`` in case of success.
917917
%End
918918

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

930-
:return: true in case of success.
930+
:return: ``True`` in case of success.
931931
%End
932932

933933
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
939939
:param errorMessage: reference to string that will be updated with any error messages
940940
:param props: a open ended set of properties that can drive/inform the SLD encoding
941941

942-
:return: true in case of success
942+
:return: ``True`` in case of success
943943
%End
944944

945945
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
976976
:param dataSource: new layer data source
977977
:param baseName: base name of the layer
978978
:param provider: provider string
979-
:param loadDefaultStyleFlag: set to true to reset the layer's style to the default for the
979+
:param loadDefaultStyleFlag: set to ``True`` to reset the layer's style to the default for the
980980
data source
981981

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

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

1032-
:return: true, when setting the subset string was successful, false otherwise
1032+
:return: ``True``, when setting the subset string was successful, ``False`` otherwise
10331033
%End
10341034

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

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

1091-
Returns true if the feature's attribute was successfully changed.
1091+
Returns ``True`` if the feature's attribute was successfully changed.
10921092

10931093
.. note::
10941094

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

1198-
:return: true in case of success and false otherwise
1198+
:return: ``True`` in case of success and ``False`` otherwise
11991199
%End
12001200

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

13381338
:param splitLine: line that splits the layer features
1339-
:param topologicalEditing: true if topological editing is enabled
1339+
:param topologicalEditing: ``True`` if topological editing is enabled
13401340

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

13621362
:param splitLine: line that splits the layer features
1363-
:param topologicalEditing: true if topological editing is enabled
1363+
:param topologicalEditing: ``True`` if topological editing is enabled
13641364

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

14261426
.. note::
14271427

1428-
Labels will only be rendered if labelsEnabled() returns true.
1428+
Labels will only be rendered if labelsEnabled() returns ``True``.
14291429

14301430
.. seealso:: :py:func:`labelsEnabled`
14311431

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

14441444
%Docstring
1445-
Returns true if the provider is in editing mode
1445+
Returns ``True`` if the provider is in editing mode
14461446
%End
14471447

14481448
virtual bool isSpatial() const ${SIP_FINAL};
14491449

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

14541454
virtual bool isModified() const;
14551455
%Docstring
1456-
Returns true if the provider has been modified since the last commit
1456+
Returns ``True`` if the provider has been modified since the last commit
14571457
%End
14581458

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

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

1518-
:return: false if the layer is in editing yet
1518+
:return: ``False`` if the layer is in editing yet
15191519
%End
15201520

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

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

1530-
Returns true if the feature's geometry was successfully changed.
1530+
Returns ``True`` if the feature's geometry was successfully changed.
15311531

15321532
.. note::
15331533

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

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

1567-
Returns true if the feature's attribute was successfully changed.
1567+
Returns ``True`` if the feature's attribute was successfully changed.
15681568

15691569
.. note::
15701570

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

1601-
If ``skipDefaultValues`` is set to true, default field values will not
1601+
If ``skipDefaultValues`` is set to ``True``, default field values will not
16021602
be updated. This can be used to override default field value
16031603
expressions.
16041604

1605-
Returns true if feature's attributes was successfully changed.
1605+
Returns ``True`` if feature's attributes was successfully changed.
16061606

16071607
.. note::
16081608

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

16341634
.. note::
16351635

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

17271727
:param attrs: the indices of the attributes to delete
17281728

1729-
:return: true if at least one attribute has been deleted
1729+
:return: ``True`` if at least one attribute has been deleted
17301730
%End
17311731

17321732
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)
17501750

17511751
:param fids: The feature ids to delete
17521752

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

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

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

1800-
If ``deleteBuffer`` is true the editing buffer will be completely deleted (the default
1800+
If ``deleteBuffer`` is ``True`` the editing buffer will be completely deleted (the default
18011801
behavior).
18021802

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

20932093
:return: calculated aggregate value
20942094

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

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

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

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

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

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

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

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

23392339
void layerModified();

0 commit comments

Comments
 (0)