Make doxygen_space script convert multiline //! comments

Because:
- the /** format is much more prevalent throughout QGIS
- sipify works correctly with /**

Author: nyalldawson

python/analysis/raster/qgsalignraster.sip

@@ -148,9 +148,12 @@ used for rescaling of values (if necessary)
 
     struct ProgressHandler
     {
+
       virtual bool progress( double complete ) = 0;
 %Docstring
-:return: false if the execution should be canceled, true otherwise
+ Method to be overridden for progress reporting.
+ \param complete Overall progress of the alignment operation
+ :return: false if the execution should be canceled, true otherwise
  :rtype: bool
 %End
 
@@ -209,44 +212,63 @@ Get the output CRS in WKT format
 
     void setClipExtent( double xmin, double ymin, double xmax, double ymax );
 %Docstring
-No extra clipping is done if the rectangle is null
+ Configure clipping extent (region of interest).
+ No extra clipping is done if the rectangle is null
 %End
+
     void setClipExtent( const QgsRectangle &extent );
 %Docstring
-No extra clipping is done if the rectangle is null
+ Configure clipping extent (region of interest).
+ No extra clipping is done if the rectangle is null
 %End
+
     QgsRectangle clipExtent() const;
 %Docstring
-No extra clipping is done if the rectangle is null
+ Get clipping extent (region of interest).
+ No extra clipping is done if the rectangle is null
  :rtype: QgsRectangle
 %End
 
     bool setParametersFromRaster( const RasterInfo &rasterInfo, const QString &customCRSWkt = QString(), QSizeF customCellSize = QSizeF(), QPointF customGridOffset = QPointF( -1, -1 ) );
 %Docstring
-:return: true on success (may fail if it is not possible to reproject raster to given CRS)
+ Set destination CRS, cell size and grid offset from a raster file.
+ The user may provide custom values for some of the parameters - in such case
+ only the remaining parameters are calculated.
+
+ If default CRS is used, the parameters are set according to the raster file's geo-transform.
+ If a custom CRS is provided, suggested reprojection is calculated first (using GDAL) in order
+ to determine suitable defaults for cell size and grid offset.
+
+ :return: true on success (may fail if it is not possible to reproject raster to given CRS)
  :rtype: bool
 %End
+
     bool setParametersFromRaster( const QString &filename, const QString &customCRSWkt = QString(), QSizeF customCellSize = QSizeF(), QPointF customGridOffset = QPointF( -1, -1 ) );
 %Docstring
-See the other variant for details.
+ Overridden variant for convenience, taking filename instead RasterInfo object.
+ See the other variant for details.
  :rtype: bool
 %End
 
     bool checkInputParameters();
 %Docstring
-:return: true on success, sets error on error (see errorMessage())
+ Determine destination extent from the input rasters and calculate derived values
+ :return: true on success, sets error on error (see errorMessage())
  :rtype: bool
 %End
 
     QSize alignedRasterSize() const;
 %Docstring
+ Return expected size of the resulting aligned raster
 .. note::
 
    first need to run checkInputParameters() which returns with success
  :rtype: QSize
 %End
+
     QgsRectangle alignedRasterExtent() const;
 %Docstring
+ Return expected extent of the resulting aligned raster
 .. note::
 
    first need to run checkInputParameters() which returns with success
@@ -255,13 +277,15 @@ See the other variant for details.
 
     bool run();
 %Docstring
-:return: true on success, sets error on error (see errorMessage())
+ Run the alignment process
+ :return: true on success, sets error on error (see errorMessage())
  :rtype: bool
 %End
 
     QString errorMessage() const;
 %Docstring
-Error message is empty if run() succeeded (returned true)
+ Return error from a previous run() call.
+ Error message is empty if run() succeeded (returned true)
  :rtype: str
 %End
 

python/analysis/raster/qgsrastermatrix.sip

@@ -67,6 +67,7 @@ Returns true if matrix is 1x1 (=scalar number)
 %End
 
 
+
     void setData( int cols, int rows, double *data, double nodataValue );
 
     int nColumns() const;

python/core/composer/qgscomposerlegend.sip

@@ -108,26 +108,34 @@ Sets item box to the whole content
 
     void setLegendFilterByMapEnabled( bool enabled );
 %Docstring
+ Set whether legend items should be filtered to show just the ones visible in the associated map
 .. versionadded:: 2.6
 %End
+
     bool legendFilterByMapEnabled() const;
 %Docstring
+ Find out whether legend items are filtered to show just the ones visible in the associated map
 .. versionadded:: 2.6
  :rtype: bool
 %End
 
     virtual void updateItem();
 %Docstring
+ Update() overloading. Use it rather than update()
 .. versionadded:: 2.12
 %End
 
     void setLegendFilterOutAtlas( bool doFilter );
 %Docstring
+ When set to true, during an atlas rendering, it will filter out legend elements
+ where features are outside the current atlas feature.
 .. versionadded:: 2.14
 %End
 
     bool legendFilterOutAtlas() const;
 %Docstring
+ Whether to filter out legend elements outside of the current atlas feature
+.. seealso:: setLegendFilterOutAtlas()
 .. versionadded:: 2.14
  :rtype: bool
 %End

python/core/dxf/qgsdxfexport.sip

@@ -257,31 +257,52 @@ class QgsDxfExport
 
     void writeLine( const QgsPoint &pt1, const QgsPoint &pt2, const QString &layer, const QString &lineStyleName, const QColor &color, double width = -1 );
 %Docstring
+ Write line (as a polyline)
 .. versionadded:: 2.15
 %End
 
     void writePoint( const QString &layer, const QColor &color, const QgsPoint &pt ) /PyName=writePointV2/;
 %Docstring
+ Write point
+.. note::
+
+   available in Python bindings as writePointV2
 .. versionadded:: 2.15
 %End
 
     void writeFilledCircle( const QString &layer, const QColor &color, const QgsPoint &pt, double radius ) /PyName=writeFillCircleV2/;
 %Docstring
+ Write filled circle (as hatch)
+.. note::
+
+   available in Python bindings as writePointV2
 .. versionadded:: 2.15
 %End
 
     void writeCircle( const QString &layer, const QColor &color, const QgsPoint &pt, double radius, const QString &lineStyleName, double width ) /PyName=writeCircleV2/;
 %Docstring
+ Write circle (as polyline)
+.. note::
+
+   available in Python bindings as writeCircleV2
 .. versionadded:: 2.15
 %End
 
     void writeText( const QString &layer, const QString &text, const QgsPoint &pt, double size, double angle, const QColor &color ) /PyName=writeTextV2/;
 %Docstring
+ Write text (TEXT)
+.. note::
+
+   available in Python bindings as writeTextV2
 .. versionadded:: 2.15
 %End
 
     void writeMText( const QString &layer, const QString &text, const QgsPoint &pt, double width, double angle, const QColor &color );
 %Docstring
+ Write mtext (MTEXT)
+.. note::
+
+   available in Python bindings as writeMTextV2
 .. versionadded:: 2.15
 %End
 

python/core/expression/qgsexpression.sip

@@ -245,13 +245,18 @@ Set evaluation error (used internally by evaluation functions)
 
     QString expression() const;
 %Docstring
-API calls, dump() will be used to create one instead.
+ Return the original, unmodified expression string.
+ If there was none supplied because it was constructed by sole
+ API calls, dump() will be used to create one instead.
  :rtype: str
 %End
 
     QString dump() const;
 %Docstring
-expression() instead.
+ Return an expression string, constructed from the internal
+ abstract syntax tree. This does not contain any nice whitespace
+ formatting or comments. In general it is preferable to use
+ expression() instead.
  :rtype: str
 %End
 

python/core/expression/qgsexpressionnode.sip

@@ -113,6 +113,7 @@ Takes ownership of the provided node
 
         bool hasNamedNodes() const;
 %Docstring
+ Returns true if list contains any named nodes
 .. versionadded:: 2.16
  :rtype: bool
 %End
@@ -133,6 +134,7 @@ Takes ownership of the provided node
 
         QStringList names() const;
 %Docstring
+ Returns a list of names for nodes. Unnamed nodes will be indicated by an empty string in the list.
 .. versionadded:: 2.16
  :rtype: list of str
 %End

python/core/layertree/qgslayertreemodel.sip

@@ -38,9 +38,11 @@ class QgsLayerTreeModel : QAbstractItemModel
       sipType = 0;
 %End
   public:
+
     explicit QgsLayerTreeModel( QgsLayerTree *rootNode, QObject *parent /TransferThis/ = 0 );
 %Docstring
-The root node is not transferred by the model.
+ Construct a new tree model with given layer tree (root node must not be null pointer).
+ The root node is not transferred by the model.
 %End
 
     ~QgsLayerTreeModel();
@@ -112,45 +114,62 @@ Check whether a flag is enabled
 
     QgsLayerTreeNode *index2node( const QModelIndex &index ) const;
 %Docstring
-Returns null pointer if index does not refer to a layer tree node (e.g. it is a legend node)
+ Return layer tree node for given index. Returns root node for invalid index.
+ Returns null pointer if index does not refer to a layer tree node (e.g. it is a legend node)
  :rtype: QgsLayerTreeNode
 %End
     QModelIndex node2index( QgsLayerTreeNode *node ) const;
 %Docstring
 Return index for a given node. If the node does not belong to the layer tree, the result is undefined
  :rtype: QModelIndex
 %End
+
     QList<QgsLayerTreeNode *> indexes2nodes( const QModelIndexList &list, bool skipInternal = false ) const;
 %Docstring
-@arg skipInternal If true, a node is included in the output list only if no parent node is in the list
+ Convert a list of indexes to a list of layer tree nodes.
+ Indices that do not represent layer tree nodes are skipped.
+ \param skipInternal If true, a node is included in the output list only if no parent node is in the list
  :rtype: list of QgsLayerTreeNode
 %End
 
     static QgsLayerTreeModelLegendNode *index2legendNode( const QModelIndex &index );
 %Docstring
+ Return legend node for given index. Returns null for invalid index
 .. versionadded:: 2.6
  :rtype: QgsLayerTreeModelLegendNode
 %End
+
     QModelIndex legendNode2index( QgsLayerTreeModelLegendNode *legendNode );
 %Docstring
+ Return index for a given legend node. If the legend node does not belong to the layer tree, the result is undefined.
+ If the legend node is belongs to the tree but it is filtered out, invalid model index is returned.
 .. versionadded:: 2.6
  :rtype: QModelIndex
 %End
 
     QList<QgsLayerTreeModelLegendNode *> layerLegendNodes( QgsLayerTreeLayer *nodeLayer, bool skipNodeEmbeddedInParent = false );
 %Docstring
+ Return filtered list of active legend nodes attached to a particular layer node
+ (by default it returns also legend node embedded in parent layer node (if any) unless skipNodeEmbeddedInParent is true)
+.. versionadded:: 2.6
+.. note::
+
+   Parameter skipNodeEmbeddedInParent added in QGIS 2.18
 .. seealso:: layerOriginalLegendNodes()
  :rtype: list of QgsLayerTreeModelLegendNode
 %End
 
     QList<QgsLayerTreeModelLegendNode *> layerOriginalLegendNodes( QgsLayerTreeLayer *nodeLayer );
 %Docstring
+ Return original (unfiltered) list of legend nodes attached to a particular layer node
+.. versionadded:: 2.14
 .. seealso:: layerLegendNodes()
  :rtype: list of QgsLayerTreeModelLegendNode
 %End
 
     QgsLayerTreeModelLegendNode *legendNodeEmbeddedInParent( QgsLayerTreeLayer *nodeLayer ) const;
 %Docstring
+ Return legend node that may be embedded in parent (i.e. its icon will be used for layer's icon).
 .. versionadded:: 2.18
  :rtype: QgsLayerTreeModelLegendNode
 %End
@@ -171,14 +190,17 @@ Return index for a given node. If the node does not belong to the layer tree, th
 Return pointer to the root node of the layer tree. Always a non-null pointer.
  :rtype: QgsLayerTree
 %End
+
     void setRootGroup( QgsLayerTree *newRootGroup );
 %Docstring
+ Reset the model and use a new root group node
 .. versionadded:: 2.6
 %End
 
     void refreshLayerLegend( QgsLayerTreeLayer *nodeLayer );
 %Docstring
-Not necessary to call when layer's renderer is changed as the model listens to these events.
+ Force a refresh of legend nodes of a layer node.
+ Not necessary to call when layer's renderer is changed as the model listens to these events.
 %End
 
     QModelIndex currentIndex() const;
@@ -232,36 +254,53 @@ Return at what number of legend nodes the layer node should be collapsed. -1 mea
 
     void setLegendFilterByMap( const QgsMapSettings *settings );
 %Docstring
+ Force only display of legend nodes which are valid for given map settings.
+ Setting null pointer or invalid map settings will disable the functionality.
+ Ownership of map settings pointer does not change, a copy is made.
 .. versionadded:: 2.6
 %End
 
     void setLegendFilter( const QgsMapSettings *settings, bool useExtent = true, const QgsGeometry &polygon = QgsGeometry(), bool useExpressions = true );
 %Docstring
+ Filter display of legend nodes for given map settings
+ \param settings Map settings. Setting a null pointer or invalid settings will disable any filter. Ownership is not changed, a copy is made
+ \param useExtent Whether to use the extent of the map settings as a first spatial filter on legend nodes
+ \param polygon If not empty, this polygon will be used instead of the map extent to filter legend nodes
+ \param useExpressions Whether to use legend node filter expressions
 .. versionadded:: 2.14
 %End
 
     const QgsMapSettings *legendFilterMapSettings() const;
 %Docstring
+ Returns the current map settings used for the current legend filter (or null if none is enabled)
 .. versionadded:: 2.14
  :rtype: QgsMapSettings
 %End
 
     void setLegendMapViewData( double mapUnitsPerPixel, int dpi, double scale );
 %Docstring
+ Give the layer tree model hints about the currently associated map view
+ so that legend nodes that use map units can be scaled currectly
 .. versionadded:: 2.6
 %End
+
     void legendMapViewData( double *mapUnitsPerPixel /Out/, int *dpi /Out/, double *scale  /Out/ ) const;
 %Docstring
+ Get hints about map view - to be used in legend nodes. Arguments that are not null will receive values.
+ If there are no valid map view data (from previous call to setLegendMapViewData()), returned values are zeros.
 .. versionadded:: 2.6
 %End
 
     QMap<QString, QString> layerStyleOverrides() const;
 %Docstring
+ 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
 .. versionadded:: 2.10
  :rtype: QMap<str, QString>
 %End
+
     void setLayerStyleOverrides( const QMap<QString, QString> &overrides );
 %Docstring
+ 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
 .. versionadded:: 2.10
 %End
 
@@ -272,8 +311,10 @@ Return at what number of legend nodes the layer node should be collapsed. -1 mea
     void nodeRemovedChildren();
 
     void nodeVisibilityChanged( QgsLayerTreeNode *node );
+
     void nodeNameChanged( QgsLayerTreeNode *node, const QString &name );
 %Docstring
+ Updates model when node's name has changed
 .. versionadded:: 3.0
 %End