Skip to content

Commit 49b426d

Browse files
committed
Make doxygen_space script convert multiline //! comments
Because: - the /** format is much more prevalent throughout QGIS - sipify works correctly with /**
1 parent d9952b6 commit 49b426d

File tree

213 files changed

+2553
-1144
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

213 files changed

+2553
-1144
lines changed

python/analysis/raster/qgsalignraster.sip

Lines changed: 33 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -148,9 +148,12 @@ used for rescaling of values (if necessary)
148148

149149
struct ProgressHandler
150150
{
151+
151152
virtual bool progress( double complete ) = 0;
152153
%Docstring
153-
:return: false if the execution should be canceled, true otherwise
154+
Method to be overridden for progress reporting.
155+
\param complete Overall progress of the alignment operation
156+
:return: false if the execution should be canceled, true otherwise
154157
:rtype: bool
155158
%End
156159

@@ -209,44 +212,63 @@ Get the output CRS in WKT format
209212

210213
void setClipExtent( double xmin, double ymin, double xmax, double ymax );
211214
%Docstring
212-
No extra clipping is done if the rectangle is null
215+
Configure clipping extent (region of interest).
216+
No extra clipping is done if the rectangle is null
213217
%End
218+
214219
void setClipExtent( const QgsRectangle &extent );
215220
%Docstring
216-
No extra clipping is done if the rectangle is null
221+
Configure clipping extent (region of interest).
222+
No extra clipping is done if the rectangle is null
217223
%End
224+
218225
QgsRectangle clipExtent() const;
219226
%Docstring
220-
No extra clipping is done if the rectangle is null
227+
Get clipping extent (region of interest).
228+
No extra clipping is done if the rectangle is null
221229
:rtype: QgsRectangle
222230
%End
223231

224232
bool setParametersFromRaster( const RasterInfo &rasterInfo, const QString &customCRSWkt = QString(), QSizeF customCellSize = QSizeF(), QPointF customGridOffset = QPointF( -1, -1 ) );
225233
%Docstring
226-
:return: true on success (may fail if it is not possible to reproject raster to given CRS)
234+
Set destination CRS, cell size and grid offset from a raster file.
235+
The user may provide custom values for some of the parameters - in such case
236+
only the remaining parameters are calculated.
237+
238+
If default CRS is used, the parameters are set according to the raster file's geo-transform.
239+
If a custom CRS is provided, suggested reprojection is calculated first (using GDAL) in order
240+
to determine suitable defaults for cell size and grid offset.
241+
242+
:return: true on success (may fail if it is not possible to reproject raster to given CRS)
227243
:rtype: bool
228244
%End
245+
229246
bool setParametersFromRaster( const QString &filename, const QString &customCRSWkt = QString(), QSizeF customCellSize = QSizeF(), QPointF customGridOffset = QPointF( -1, -1 ) );
230247
%Docstring
231-
See the other variant for details.
248+
Overridden variant for convenience, taking filename instead RasterInfo object.
249+
See the other variant for details.
232250
:rtype: bool
233251
%End
234252

235253
bool checkInputParameters();
236254
%Docstring
237-
:return: true on success, sets error on error (see errorMessage())
255+
Determine destination extent from the input rasters and calculate derived values
256+
:return: true on success, sets error on error (see errorMessage())
238257
:rtype: bool
239258
%End
240259

241260
QSize alignedRasterSize() const;
242261
%Docstring
262+
Return expected size of the resulting aligned raster
243263
.. note::
244264

245265
first need to run checkInputParameters() which returns with success
246266
:rtype: QSize
247267
%End
268+
248269
QgsRectangle alignedRasterExtent() const;
249270
%Docstring
271+
Return expected extent of the resulting aligned raster
250272
.. note::
251273

252274
first need to run checkInputParameters() which returns with success
@@ -255,13 +277,15 @@ See the other variant for details.
255277

256278
bool run();
257279
%Docstring
258-
:return: true on success, sets error on error (see errorMessage())
280+
Run the alignment process
281+
:return: true on success, sets error on error (see errorMessage())
259282
:rtype: bool
260283
%End
261284

262285
QString errorMessage() const;
263286
%Docstring
264-
Error message is empty if run() succeeded (returned true)
287+
Return error from a previous run() call.
288+
Error message is empty if run() succeeded (returned true)
265289
:rtype: str
266290
%End
267291

python/analysis/raster/qgsrastermatrix.sip

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ Returns true if matrix is 1x1 (=scalar number)
6767
%End
6868

6969

70+
7071
void setData( int cols, int rows, double *data, double nodataValue );
7172

7273
int nColumns() const;

python/core/composer/qgscomposerlegend.sip

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,26 +108,34 @@ Sets item box to the whole content
108108

109109
void setLegendFilterByMapEnabled( bool enabled );
110110
%Docstring
111+
Set whether legend items should be filtered to show just the ones visible in the associated map
111112
.. versionadded:: 2.6
112113
%End
114+
113115
bool legendFilterByMapEnabled() const;
114116
%Docstring
117+
Find out whether legend items are filtered to show just the ones visible in the associated map
115118
.. versionadded:: 2.6
116119
:rtype: bool
117120
%End
118121

119122
virtual void updateItem();
120123
%Docstring
124+
Update() overloading. Use it rather than update()
121125
.. versionadded:: 2.12
122126
%End
123127

124128
void setLegendFilterOutAtlas( bool doFilter );
125129
%Docstring
130+
When set to true, during an atlas rendering, it will filter out legend elements
131+
where features are outside the current atlas feature.
126132
.. versionadded:: 2.14
127133
%End
128134

129135
bool legendFilterOutAtlas() const;
130136
%Docstring
137+
Whether to filter out legend elements outside of the current atlas feature
138+
.. seealso:: setLegendFilterOutAtlas()
131139
.. versionadded:: 2.14
132140
:rtype: bool
133141
%End

python/core/dxf/qgsdxfexport.sip

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -257,31 +257,52 @@ class QgsDxfExport
257257

258258
void writeLine( const QgsPoint &pt1, const QgsPoint &pt2, const QString &layer, const QString &lineStyleName, const QColor &color, double width = -1 );
259259
%Docstring
260+
Write line (as a polyline)
260261
.. versionadded:: 2.15
261262
%End
262263

263264
void writePoint( const QString &layer, const QColor &color, const QgsPoint &pt ) /PyName=writePointV2/;
264265
%Docstring
266+
Write point
267+
.. note::
268+
269+
available in Python bindings as writePointV2
265270
.. versionadded:: 2.15
266271
%End
267272

268273
void writeFilledCircle( const QString &layer, const QColor &color, const QgsPoint &pt, double radius ) /PyName=writeFillCircleV2/;
269274
%Docstring
275+
Write filled circle (as hatch)
276+
.. note::
277+
278+
available in Python bindings as writePointV2
270279
.. versionadded:: 2.15
271280
%End
272281

273282
void writeCircle( const QString &layer, const QColor &color, const QgsPoint &pt, double radius, const QString &lineStyleName, double width ) /PyName=writeCircleV2/;
274283
%Docstring
284+
Write circle (as polyline)
285+
.. note::
286+
287+
available in Python bindings as writeCircleV2
275288
.. versionadded:: 2.15
276289
%End
277290

278291
void writeText( const QString &layer, const QString &text, const QgsPoint &pt, double size, double angle, const QColor &color ) /PyName=writeTextV2/;
279292
%Docstring
293+
Write text (TEXT)
294+
.. note::
295+
296+
available in Python bindings as writeTextV2
280297
.. versionadded:: 2.15
281298
%End
282299

283300
void writeMText( const QString &layer, const QString &text, const QgsPoint &pt, double width, double angle, const QColor &color );
284301
%Docstring
302+
Write mtext (MTEXT)
303+
.. note::
304+
305+
available in Python bindings as writeMTextV2
285306
.. versionadded:: 2.15
286307
%End
287308

python/core/expression/qgsexpression.sip

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -245,13 +245,18 @@ Set evaluation error (used internally by evaluation functions)
245245

246246
QString expression() const;
247247
%Docstring
248-
API calls, dump() will be used to create one instead.
248+
Return the original, unmodified expression string.
249+
If there was none supplied because it was constructed by sole
250+
API calls, dump() will be used to create one instead.
249251
:rtype: str
250252
%End
251253

252254
QString dump() const;
253255
%Docstring
254-
expression() instead.
256+
Return an expression string, constructed from the internal
257+
abstract syntax tree. This does not contain any nice whitespace
258+
formatting or comments. In general it is preferable to use
259+
expression() instead.
255260
:rtype: str
256261
%End
257262

python/core/expression/qgsexpressionnode.sip

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,7 @@ Takes ownership of the provided node
113113

114114
bool hasNamedNodes() const;
115115
%Docstring
116+
Returns true if list contains any named nodes
116117
.. versionadded:: 2.16
117118
:rtype: bool
118119
%End
@@ -133,6 +134,7 @@ Takes ownership of the provided node
133134

134135
QStringList names() const;
135136
%Docstring
137+
Returns a list of names for nodes. Unnamed nodes will be indicated by an empty string in the list.
136138
.. versionadded:: 2.16
137139
:rtype: list of str
138140
%End

python/core/layertree/qgslayertreemodel.sip

Lines changed: 45 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,11 @@ class QgsLayerTreeModel : QAbstractItemModel
3838
sipType = 0;
3939
%End
4040
public:
41+
4142
explicit QgsLayerTreeModel( QgsLayerTree *rootNode, QObject *parent /TransferThis/ = 0 );
4243
%Docstring
43-
The root node is not transferred by the model.
44+
Construct a new tree model with given layer tree (root node must not be null pointer).
45+
The root node is not transferred by the model.
4446
%End
4547

4648
~QgsLayerTreeModel();
@@ -112,45 +114,62 @@ Check whether a flag is enabled
112114

113115
QgsLayerTreeNode *index2node( const QModelIndex &index ) const;
114116
%Docstring
115-
Returns null pointer if index does not refer to a layer tree node (e.g. it is a legend node)
117+
Return layer tree node for given index. Returns root node for invalid index.
118+
Returns null pointer if index does not refer to a layer tree node (e.g. it is a legend node)
116119
:rtype: QgsLayerTreeNode
117120
%End
118121
QModelIndex node2index( QgsLayerTreeNode *node ) const;
119122
%Docstring
120123
Return index for a given node. If the node does not belong to the layer tree, the result is undefined
121124
:rtype: QModelIndex
122125
%End
126+
123127
QList<QgsLayerTreeNode *> indexes2nodes( const QModelIndexList &list, bool skipInternal = false ) const;
124128
%Docstring
125-
@arg skipInternal If true, a node is included in the output list only if no parent node is in the list
129+
Convert a list of indexes to a list of layer tree nodes.
130+
Indices that do not represent layer tree nodes are skipped.
131+
\param skipInternal If true, a node is included in the output list only if no parent node is in the list
126132
:rtype: list of QgsLayerTreeNode
127133
%End
128134

129135
static QgsLayerTreeModelLegendNode *index2legendNode( const QModelIndex &index );
130136
%Docstring
137+
Return legend node for given index. Returns null for invalid index
131138
.. versionadded:: 2.6
132139
:rtype: QgsLayerTreeModelLegendNode
133140
%End
141+
134142
QModelIndex legendNode2index( QgsLayerTreeModelLegendNode *legendNode );
135143
%Docstring
144+
Return index for a given legend node. If the legend node does not belong to the layer tree, the result is undefined.
145+
If the legend node is belongs to the tree but it is filtered out, invalid model index is returned.
136146
.. versionadded:: 2.6
137147
:rtype: QModelIndex
138148
%End
139149

140150
QList<QgsLayerTreeModelLegendNode *> layerLegendNodes( QgsLayerTreeLayer *nodeLayer, bool skipNodeEmbeddedInParent = false );
141151
%Docstring
152+
Return filtered list of active legend nodes attached to a particular layer node
153+
(by default it returns also legend node embedded in parent layer node (if any) unless skipNodeEmbeddedInParent is true)
154+
.. versionadded:: 2.6
155+
.. note::
156+
157+
Parameter skipNodeEmbeddedInParent added in QGIS 2.18
142158
.. seealso:: layerOriginalLegendNodes()
143159
:rtype: list of QgsLayerTreeModelLegendNode
144160
%End
145161

146162
QList<QgsLayerTreeModelLegendNode *> layerOriginalLegendNodes( QgsLayerTreeLayer *nodeLayer );
147163
%Docstring
164+
Return original (unfiltered) list of legend nodes attached to a particular layer node
165+
.. versionadded:: 2.14
148166
.. seealso:: layerLegendNodes()
149167
:rtype: list of QgsLayerTreeModelLegendNode
150168
%End
151169

152170
QgsLayerTreeModelLegendNode *legendNodeEmbeddedInParent( QgsLayerTreeLayer *nodeLayer ) const;
153171
%Docstring
172+
Return legend node that may be embedded in parent (i.e. its icon will be used for layer's icon).
154173
.. versionadded:: 2.18
155174
:rtype: QgsLayerTreeModelLegendNode
156175
%End
@@ -171,14 +190,17 @@ Return index for a given node. If the node does not belong to the layer tree, th
171190
Return pointer to the root node of the layer tree. Always a non-null pointer.
172191
:rtype: QgsLayerTree
173192
%End
193+
174194
void setRootGroup( QgsLayerTree *newRootGroup );
175195
%Docstring
196+
Reset the model and use a new root group node
176197
.. versionadded:: 2.6
177198
%End
178199

179200
void refreshLayerLegend( QgsLayerTreeLayer *nodeLayer );
180201
%Docstring
181-
Not necessary to call when layer's renderer is changed as the model listens to these events.
202+
Force a refresh of legend nodes of a layer node.
203+
Not necessary to call when layer's renderer is changed as the model listens to these events.
182204
%End
183205

184206
QModelIndex currentIndex() const;
@@ -232,36 +254,53 @@ Return at what number of legend nodes the layer node should be collapsed. -1 mea
232254

233255
void setLegendFilterByMap( const QgsMapSettings *settings );
234256
%Docstring
257+
Force only display of legend nodes which are valid for given map settings.
258+
Setting null pointer or invalid map settings will disable the functionality.
259+
Ownership of map settings pointer does not change, a copy is made.
235260
.. versionadded:: 2.6
236261
%End
237262

238263
void setLegendFilter( const QgsMapSettings *settings, bool useExtent = true, const QgsGeometry &polygon = QgsGeometry(), bool useExpressions = true );
239264
%Docstring
265+
Filter display of legend nodes for given map settings
266+
\param settings Map settings. Setting a null pointer or invalid settings will disable any filter. Ownership is not changed, a copy is made
267+
\param useExtent Whether to use the extent of the map settings as a first spatial filter on legend nodes
268+
\param polygon If not empty, this polygon will be used instead of the map extent to filter legend nodes
269+
\param useExpressions Whether to use legend node filter expressions
240270
.. versionadded:: 2.14
241271
%End
242272

243273
const QgsMapSettings *legendFilterMapSettings() const;
244274
%Docstring
275+
Returns the current map settings used for the current legend filter (or null if none is enabled)
245276
.. versionadded:: 2.14
246277
:rtype: QgsMapSettings
247278
%End
248279

249280
void setLegendMapViewData( double mapUnitsPerPixel, int dpi, double scale );
250281
%Docstring
282+
Give the layer tree model hints about the currently associated map view
283+
so that legend nodes that use map units can be scaled currectly
251284
.. versionadded:: 2.6
252285
%End
286+
253287
void legendMapViewData( double *mapUnitsPerPixel /Out/, int *dpi /Out/, double *scale /Out/ ) const;
254288
%Docstring
289+
Get hints about map view - to be used in legend nodes. Arguments that are not null will receive values.
290+
If there are no valid map view data (from previous call to setLegendMapViewData()), returned values are zeros.
255291
.. versionadded:: 2.6
256292
%End
257293

258294
QMap<QString, QString> layerStyleOverrides() const;
259295
%Docstring
296+
Get map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one
260297
.. versionadded:: 2.10
261298
:rtype: QMap<str, QString>
262299
%End
300+
263301
void setLayerStyleOverrides( const QMap<QString, QString> &overrides );
264302
%Docstring
303+
Set map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one
265304
.. versionadded:: 2.10
266305
%End
267306

@@ -272,8 +311,10 @@ Return at what number of legend nodes the layer node should be collapsed. -1 mea
272311
void nodeRemovedChildren();
273312

274313
void nodeVisibilityChanged( QgsLayerTreeNode *node );
314+
275315
void nodeNameChanged( QgsLayerTreeNode *node, const QString &name );
276316
%Docstring
317+
Updates model when node's name has changed
277318
.. versionadded:: 3.0
278319
%End
279320

0 commit comments

Comments
 (0)