From bd32078635cd4ccc7e2891c98452928932bf5782 Mon Sep 17 00:00:00 2001
From: Denis Rouzaud <denis.rouzaud@gmail.com>
Date: Wed, 19 Dec 2018 08:03:47 -0400
Subject: [PATCH 1/3] [sipify] enhanced SIP_OUT handling

return an error if method with SIP_OUT arguments has no \return directive AND is not void
create list of outputs for better visualization
---
 scripts/sipify.pl | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/scripts/sipify.pl b/scripts/sipify.pl
index f5b4e3ff8d51..c0a0f8514711 100755
--- a/scripts/sipify.pl
+++ b/scripts/sipify.pl
@@ -1235,12 +1235,17 @@ sub detect_non_method_member{
                       next;
                     }
                   }
-                  write_output("CM2", "$doc_prepend$comment_line\n");
                   if ( $comment_line =~ m/:return:/ && $#out_params >= 0 ){
                     $waiting_for_return_to_end = 1;
+                    $comment_line =~ s/:return:/:return: -/;
+                    write_output("CM2", "$doc_prepend$comment_line\n");
                     foreach my $out_param (@out_params) {
-                      write_output("CM7", "$doc_prepend         $out_param\n");
+                      write_output("CM7", "$doc_prepend         - $out_param\n");
                     }
+                    @out_params = ();
+                  }
+                  else {
+                    write_output("CM2", "$doc_prepend$comment_line\n");
                   }
                   if ( $waiting_for_return_to_end == 1 ) {
                     if ($comment_line =~ m/^(:.*|\.\..*|\s*)$/) {
@@ -1256,7 +1261,8 @@ sub detect_non_method_member{
                   #     $RETURN_TYPE = '';
                   # }
                 }
-            write_output("CM4", "$doc_prepend%End\n");
+                exit_with_error("A method with output parameters must contain a return directive (method returns ${RETURN_TYPE})") if $#out_params >= 0 and $RETURN_TYPE ne '';
+                write_output("CM4", "$doc_prepend%End\n");
             }
             # if ( $RETURN_TYPE ne '' ){
             #     write_output("CM3", "\n:rtype: $RETURN_TYPE\n");

From 03f801738de754ee2467c87414c598ff499598d8 Mon Sep 17 00:00:00 2001
From: Denis Rouzaud <denis.rouzaud@gmail.com>
Date: Wed, 19 Dec 2018 08:04:17 -0400
Subject: [PATCH 2/3] fix missing \returns in source

---
 src/analysis/interpolation/qgsinterpolator.h | 5 +++--
 src/core/geometry/qgsgeometry.h              | 1 +
 src/core/qgsunittypes.h                      | 2 ++
 src/core/qgsvectorlayerjoinbuffer.h          | 8 +++++---
 src/core/qgsziputils.h                       | 6 +++---
 src/gui/qgsexpressionlineedit.h              | 3 ++-
 6 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/src/analysis/interpolation/qgsinterpolator.h b/src/analysis/interpolation/qgsinterpolator.h
index cd1dad17caae..538e1bf63dd7 100644
--- a/src/analysis/interpolation/qgsinterpolator.h
+++ b/src/analysis/interpolation/qgsinterpolator.h
@@ -110,9 +110,10 @@ class ANALYSIS_EXPORT QgsInterpolator
      * Calculates interpolation value for map coordinates x, y
      * \param x x-coordinate (in map units)
      * \param y y-coordinate (in map units)
-     * \param result out: interpolation result
+     * \param result interpolation result
      * \param feedback optional feedback object for progress and cancelation support
-     * \returns 0 in case of success*/
+     * \returns 0 in case of success
+     */
     virtual int interpolatePoint( double x, double y, double &result SIP_OUT, QgsFeedback *feedback = nullptr ) = 0;
 
     //! \note not available in Python bindings
diff --git a/src/core/geometry/qgsgeometry.h b/src/core/geometry/qgsgeometry.h
index 66925477ff99..0ab270ca2951 100644
--- a/src/core/geometry/qgsgeometry.h
+++ b/src/core/geometry/qgsgeometry.h
@@ -876,6 +876,7 @@ class CORE_EXPORT QgsGeometry
      * \param center Center of the minimal enclosing circle returneds
      * \param radius Radius of the minimal enclosing circle returned
      * \param segments Number of segments used to segment geometry. \see QgsEllipse::toPolygon()
+     * \returns the minimal enclosing circle as a QGIS geometry
      * \since QGIS 3.0
      */
     QgsGeometry minimalEnclosingCircle( QgsPointXY &center SIP_OUT, double &radius SIP_OUT, unsigned int segments = 36 ) const;
diff --git a/src/core/qgsunittypes.h b/src/core/qgsunittypes.h
index b682f4bdc7e6..4c13c55c57b6 100644
--- a/src/core/qgsunittypes.h
+++ b/src/core/qgsunittypes.h
@@ -226,6 +226,7 @@ class CORE_EXPORT QgsUnitTypes
      * Converts a translated string to a distance unit.
      * \param string string representing a distance unit
      * \param ok optional boolean, will be set to true if string was converted successfully
+     * \returns the distance unit
      * \see toString()
      */
     Q_INVOKABLE static QgsUnitTypes::DistanceUnit stringToDistanceUnit( const QString &string, bool *ok SIP_OUT = nullptr );
@@ -282,6 +283,7 @@ class CORE_EXPORT QgsUnitTypes
      * Converts a translated string to an areal unit.
      * \param string string representing an areal unit
      * \param ok optional boolean, will be set to true if string was converted successfully
+     * \returns the area unit
      * \see toString()
      */
     Q_INVOKABLE static AreaUnit stringToAreaUnit( const QString &string, bool *ok SIP_OUT = nullptr );
diff --git a/src/core/qgsvectorlayerjoinbuffer.h b/src/core/qgsvectorlayerjoinbuffer.h
index 53cb9f3a4477..cd69f1725b37 100644
--- a/src/core/qgsvectorlayerjoinbuffer.h
+++ b/src/core/qgsvectorlayerjoinbuffer.h
@@ -81,9 +81,11 @@ class CORE_EXPORT QgsVectorLayerJoinBuffer : public QObject, public QgsFeatureSi
 
     /**
      * Finds the vector join for a layer field index.
-      \param index this layers attribute index
-      \param fields fields of the vector layer (including joined fields)
-      \param sourceFieldIndex Output: field's index in source layer */
+     * \param index this layers attribute index
+     * \param fields fields of the vector layer (including joined fields)
+     * \param sourceFieldIndex Output: field's index in source layer
+     * \returns the vector layer join info
+     */
     const QgsVectorLayerJoinInfo *joinForFieldIndex( int index, const QgsFields &fields, int &sourceFieldIndex SIP_OUT ) const;
 
     /**
diff --git a/src/core/qgsziputils.h b/src/core/qgsziputils.h
index fa82360a91c2..73e689955556 100644
--- a/src/core/qgsziputils.h
+++ b/src/core/qgsziputils.h
@@ -38,12 +38,12 @@ namespace QgsZipUtils
   CORE_EXPORT bool isZipFile( const QString &filename );
 
   /**
-   * Unzip a zip file in an output directory. An error is returned if the zip
-   *  filename does not exist, the output directory does not exist or is
-   *  not writable.
+   * Unzip a zip file in an output directory.
    * \param zip The zip filename
    * \param dir The output directory
    * \param files The absolute path of unzipped files
+   * \returns false if the zip filename does not exist, the output directory
+   * does not exist or is not writable.
    * \since QGIS 3.0
    */
   CORE_EXPORT bool unzip( const QString &zip, const QString &dir, QStringList &files SIP_OUT );
diff --git a/src/gui/qgsexpressionlineedit.h b/src/gui/qgsexpressionlineedit.h
index bf92ce248f69..55d8eca04ad2 100644
--- a/src/gui/qgsexpressionlineedit.h
+++ b/src/gui/qgsexpressionlineedit.h
@@ -118,8 +118,9 @@ class GUI_EXPORT QgsExpressionLineEdit : public QWidget
     QString expression() const;
 
     /**
-      * Returns true if the current expression is valid.
+      * Determines if the current expression is valid.
       * \param expressionError will be set to any generated error message if specified
+      * \returns true if the current expression is valid.
       */
     bool isValidExpression( QString *expressionError SIP_OUT = nullptr ) const;
 

From 166e952c33eeb16b481efc2780a359639d912fed Mon Sep 17 00:00:00 2001
From: Denis Rouzaud <denis.rouzaud@gmail.com>
Date: Wed, 19 Dec 2018 08:04:27 -0400
Subject: [PATCH 3/3] run sipify

---
 .../interpolation/qgsinterpolator.sip.in      |  4 +--
 .../expression/qgsexpression.sip.in           |  4 +--
 .../geometry/qgsabstractgeometry.sip.in       |  8 +++---
 .../auto_generated/geometry/qgscurve.sip.in   |  4 +--
 .../geometry/qgsgeometry.sip.in               | 11 +++++---
 .../geometry/qgsgeometryutils.sip.in          | 16 +++++------
 .../auto_generated/qgsdistancearea.sip.in     |  4 +--
 python/core/auto_generated/qgsmaplayer.sip.in | 28 +++++++++----------
 python/core/auto_generated/qgsproperty.sip.in | 24 ++++++++--------
 .../qgspropertycollection.sip.in              | 20 ++++++-------
 .../qgspropertytransformer.sip.in             | 12 ++++----
 .../core/auto_generated/qgstransaction.sip.in |  4 +--
 .../core/auto_generated/qgsunittypes.sip.in   | 26 ++++++++++-------
 .../core/auto_generated/qgsvectorlayer.sip.in |  8 +++---
 .../qgsvectorlayerjoinbuffer.sip.in           |  3 ++
 .../auto_generated/qgsvectorlayertools.sip.in |  8 +++---
 python/core/auto_generated/qgsziputils.sip.in |  8 ++++--
 .../raster/qgsrastershader.sip.in             |  8 +++---
 .../raster/qgsrastershaderfunction.sip.in     |  8 +++---
 .../core/qgseditorwidgetautoconf.sip.in       |  4 +--
 .../qgsexpressionlineedit.sip.in              |  5 +++-
 .../auto_generated/qgsserverexception.sip.in  |  4 +--
 22 files changed, 119 insertions(+), 102 deletions(-)

diff --git a/python/analysis/auto_generated/interpolation/qgsinterpolator.sip.in b/python/analysis/auto_generated/interpolation/qgsinterpolator.sip.in
index e903b220dd7f..e5eedf7c6ea4 100644
--- a/python/analysis/auto_generated/interpolation/qgsinterpolator.sip.in
+++ b/python/analysis/auto_generated/interpolation/qgsinterpolator.sip.in
@@ -84,8 +84,8 @@ Calculates interpolation value for map coordinates x, y
 :param y: y-coordinate (in map units)
 :param feedback: optional feedback object for progress and cancelation support
 
-:return: 0 in case of success*
-         result:  out: interpolation result
+:return: - 0 in case of success
+         - result:  interpolation result
 %End
 
 
diff --git a/python/core/auto_generated/expression/qgsexpression.sip.in b/python/core/auto_generated/expression/qgsexpression.sip.in
index 47dc61744dcb..d56b66ccf6b8 100644
--- a/python/core/auto_generated/expression/qgsexpression.sip.in
+++ b/python/core/auto_generated/expression/qgsexpression.sip.in
@@ -250,8 +250,8 @@ Tests whether a string is a valid expression.
 :param text: string to test
 :param context: optional expression context
 
-:return: true if string is a valid expression
-         errorMessage:  will be filled with any error message from the validation
+:return: - true if string is a valid expression
+         - errorMessage:  will be filled with any error message from the validation
 
 .. versionadded:: 2.12
 %End
diff --git a/python/core/auto_generated/geometry/qgsabstractgeometry.sip.in b/python/core/auto_generated/geometry/qgsabstractgeometry.sip.in
index a3a2a4a62989..417e25045cef 100644
--- a/python/core/auto_generated/geometry/qgsabstractgeometry.sip.in
+++ b/python/core/auto_generated/geometry/qgsabstractgeometry.sip.in
@@ -307,8 +307,8 @@ Returns next vertex id and coordinates
 :param id: initial value should be the starting vertex id. The next vertex id will be stored
            in this variable if found.
 
-:return: false if at end
-         vertex:  container for found node
+:return: - false if at end
+         - vertex:  container for found node
 %End
 
     virtual void adjacentVertices( QgsVertexId vertex, QgsVertexId &previousVertex /Out/, QgsVertexId &nextVertex /Out/ ) const = 0;
@@ -346,8 +346,8 @@ Searches for the closest segment of the geometry to a given point.
 :param vertexAfter: storage for the ID of the vertex at the end of the closest segment
 :param epsilon: epsilon for segment snapping
 
-:return: squared distance to closest segment or negative value on error
-         leftOf:  indicates whether the point lies on the left side of the geometry (-1 if point is to the left of the geometry, +1 if the point is to the right of the geometry, or 0 for cases where left/right could not be determined, e.g. point exactly on a line) false if point is to right of segment)
+:return: - squared distance to closest segment or negative value on error
+         - leftOf:  indicates whether the point lies on the left side of the geometry (-1 if point is to the left of the geometry, +1 if the point is to the right of the geometry, or 0 for cases where left/right could not be determined, e.g. point exactly on a line) false if point is to right of segment)
 %End
 
 
diff --git a/python/core/auto_generated/geometry/qgscurve.sip.in b/python/core/auto_generated/geometry/qgscurve.sip.in
index 8f422707bbaf..829eb609234f 100644
--- a/python/core/auto_generated/geometry/qgscurve.sip.in
+++ b/python/core/auto_generated/geometry/qgscurve.sip.in
@@ -136,8 +136,8 @@ Returns the point and vertex id of a point within the curve.
 :param node: node number, where the first node is 0
 :param type: will be set to the vertex type of the node
 
-:return: true if node exists within the curve
-         point:  will be set to point at corresponding node in the curve
+:return: - true if node exists within the curve
+         - point:  will be set to point at corresponding node in the curve
 %End
 
     virtual QgsCurve *reversed() const = 0 /Factory/;
diff --git a/python/core/auto_generated/geometry/qgsgeometry.sip.in b/python/core/auto_generated/geometry/qgsgeometry.sip.in
index 9be67de2d1df..b672b1c69495 100644
--- a/python/core/auto_generated/geometry/qgsgeometry.sip.in
+++ b/python/core/auto_generated/geometry/qgsgeometry.sip.in
@@ -633,8 +633,8 @@ Searches for the closest vertex in this geometry to the given point.
 
 :param point: Specifiest the point for search
 
-:return: The squared Cartesian distance is also returned in sqrDist, negative number on error
-         atVertex:  Receives index of the closest vertex
+:return: - The squared Cartesian distance is also returned in sqrDist, negative number on error
+         - atVertex:  Receives index of the closest vertex
 %End
 
     double closestSegmentWithContext( const QgsPointXY &point, QgsPointXY &minDistPoint /Out/, int &afterVertex /Out/, int *leftOf /Out/ = 0, double epsilon = DEFAULT_SEGMENT_EPSILON ) const;
@@ -648,8 +648,8 @@ Searches for the closest segment of geometry to the given point
                that the test was unsuccessful, e.g. for a point exactly on the line)
 :param epsilon: epsilon for segment snapping
 
-:return: The squared Cartesian distance is also returned in sqrDist, negative number on error
-         minDistPoint:  Receives the nearest point on the segment
+:return: - The squared Cartesian distance is also returned in sqrDist, negative number on error
+         - minDistPoint:  Receives the nearest point on the segment
 %End
 
     OperationResult addRing( const QVector<QgsPointXY> &ring );
@@ -821,6 +821,9 @@ Returns the minimal enclosing circle for the geometry.
 :param radius: Radius of the minimal enclosing circle returned
 :param segments: Number of segments used to segment geometry. :py:func:`QgsEllipse.toPolygon`
 
+:return: - the minimal enclosing circle as a QGIS geometry
+         - center:  Center of the minimal enclosing circle returneds
+
 .. versionadded:: 3.0
 %End
 
diff --git a/python/core/auto_generated/geometry/qgsgeometryutils.sip.in b/python/core/auto_generated/geometry/qgsgeometryutils.sip.in
index 1cebd46c19b6..96f41ad95bd6 100644
--- a/python/core/auto_generated/geometry/qgsgeometryutils.sip.in
+++ b/python/core/auto_generated/geometry/qgsgeometryutils.sip.in
@@ -67,8 +67,8 @@ Retrieves the vertices which are before and after the interpolated point at a sp
 :param distance: distance to traverse along geometry
 :param previousVertex: will be set to previous vertex ID
 
-:return: true if vertices were successfully retrieved
-         nextVertex:  will be set to next vertex ID
+:return: - true if vertices were successfully retrieved
+         - nextVertex:  will be set to next vertex ID
 
 .. note::
 
@@ -98,8 +98,8 @@ supported and is retrieved from the first 3D point amongst ``p1`` and
 :param p2: Point on the second line
 :param v2: Direction vector of the second line
 
-:return: Whether the lines intersect
-         intersection:  Output parameter, the intersection point
+:return: - Whether the lines intersect
+         - intersection:  Output parameter, the intersection point
 %End
 
     static bool segmentIntersection( const QgsPoint &p1, const QgsPoint &p2, const QgsPoint &q1, const QgsPoint &q2, QgsPoint &intersectionPoint /Out/, bool &isIntersection /Out/, double tolerance = 1e-8, bool acceptImproperIntersection = false );
@@ -114,8 +114,8 @@ Compute the intersection between two segments
 :param tolerance: The tolerance to use
 :param acceptImproperIntersection: By default, this method returns true only if segments have proper intersection. If set true, returns also true if segments have improper intersection (end of one segment on other segment ; continuous segments).
 
-:return: Whether the segments intersect
-         intersectionPoint:  Output parameter, the intersection point
+:return: - Whether the segments intersect
+         - intersectionPoint:  Output parameter, the intersection point
          * Example:
 .. code-block:: python
 
@@ -574,8 +574,8 @@ An algorithm to calculate an (approximate) intersection of two lines in 3D.
 :param Lb1: is the first point on the second line,
 :param Lb2: is the second point on the second line,
 
-:return: true if the intersection can be found, false - otherwise.
-         intersection:  is the result intersection, of it can be found.
+:return: - true if the intersection can be found, false - otherwise.
+         - intersection:  is the result intersection, of it can be found.
          example:
 .. code-block:: python
 
diff --git a/python/core/auto_generated/qgsdistancearea.sip.in b/python/core/auto_generated/qgsdistancearea.sip.in
index 8bc2b268f0bd..350766db54ca 100644
--- a/python/core/auto_generated/qgsdistancearea.sip.in
+++ b/python/core/auto_generated/qgsdistancearea.sip.in
@@ -222,8 +222,8 @@ otherwise QgsPoint.project() will be called after QgsUnitTypes.fromUnitToUnitFac
 :param distance: must be in meters
 :param azimuth: - azimuth in radians, clockwise from North
 
-:return: distance in mapUnits
-         projectedPoint:  calculated projected point
+:return: - distance in mapUnits
+         - projectedPoint:  calculated projected point
 
 .. seealso:: :py:func:`sourceCrs`
 
diff --git a/python/core/auto_generated/qgsmaplayer.sip.in b/python/core/auto_generated/qgsmaplayer.sip.in
index 9c489069fce5..34e98ab0f82f 100644
--- a/python/core/auto_generated/qgsmaplayer.sip.in
+++ b/python/core/auto_generated/qgsmaplayer.sip.in
@@ -651,8 +651,8 @@ Save the current metadata of this layer as the default metadata
 record in the users style table in their personal qgis.db)
 
 
-:return: a QString with any status messages
-         resultFlag:  a reference to a flag that will be set to false if we did not manage to save the default metadata.
+:return: - a QString with any status messages
+         - resultFlag:  a reference to a flag that will be set to false if we did not manage to save the default metadata.
 
 .. versionadded:: 3.0
 %End
@@ -688,8 +688,8 @@ record in the users style table in their personal qgis.db)
             table will be consulted to see if there is a metadata who's
             key matches the URI.
 
-:return: a QString with any status messages
-         resultFlag:  a reference to a flag that will be set to false if we did not manage to load the default metadata.
+:return: - a QString with any status messages
+         - resultFlag:  a reference to a flag that will be set to false if we did not manage to load the default metadata.
 
 .. versionadded:: 3.0
 %End
@@ -751,8 +751,8 @@ exists (either as a .qml file on disk or as a
 record in the users style table in their personal qgis.db)
 
 
-:return: a QString with any status messages
-         resultFlag:  a reference to a flag that will be set to false if we did not manage to load the default style.
+:return: - a QString with any status messages
+         - resultFlag:  a reference to a flag that will be set to false if we did not manage to load the default style.
 
 .. seealso:: :py:func:`also`
 %End
@@ -770,8 +770,8 @@ record in the users style table in their personal qgis.db)
             key matches the URI.
 :param categories: the style categories to be loaded.
 
-:return: a QString with any status messages
-         resultFlag:  a reference to a flag that will be set to false if we did not manage to load the default style.
+:return: - a QString with any status messages
+         - resultFlag:  a reference to a flag that will be set to false if we did not manage to load the default style.
 
 .. seealso:: :py:func:`also`
 %End
@@ -783,8 +783,8 @@ Retrieve a named style for this layer from a sqlite database.
 :param db: path to sqlite database
 :param uri: uri for table
 
-:return: true if style was successfully loaded
-         qml:  will be set to QML style content from database
+:return: - true if style was successfully loaded
+         - qml:  will be set to QML style content from database
 %End
 
     virtual bool importNamedStyle( QDomDocument &doc, QString &errorMsg /Out/,
@@ -831,8 +831,8 @@ Save the properties of this layer as the default style
 record in the users style table in their personal qgis.db)
 
 
-:return: a QString with any status messages
-         resultFlag:  a reference to a flag that will be set to false if we did not manage to save the default style.
+:return: - a QString with any status messages
+         - resultFlag:  a reference to a flag that will be set to false if we did not manage to save the default style.
 
 .. seealso:: :py:func:`loadNamedStyle`
 %End
@@ -850,8 +850,8 @@ record in the users style table in their personal qgis.db)
             key matches the URI.
 :param categories: the style categories to be saved.
 
-:return: a QString with any status messages
-         resultFlag:  a reference to a flag that will be set to false if we did not manage to save the default style.
+:return: - a QString with any status messages
+         - resultFlag:  a reference to a flag that will be set to false if we did not manage to save the default style.
 
 .. seealso:: :py:func:`saveDefaultStyle`
 %End
diff --git a/python/core/auto_generated/qgsproperty.sip.in b/python/core/auto_generated/qgsproperty.sip.in
index d1766cc8caca..9343dde07e28 100644
--- a/python/core/auto_generated/qgsproperty.sip.in
+++ b/python/core/auto_generated/qgsproperty.sip.in
@@ -322,8 +322,8 @@ Calculates the current value of the property, including any transforms which are
                 is able to respond to the current environment, layers and features within QGIS.
 :param defaultValue: default value to return if the property is not active or cannot be calculated
 
-:return: calculated value for property
-         ok:  if specified, will be set to true if conversion was successful
+:return: - calculated value for property
+         - ok:  if specified, will be set to true if conversion was successful
 
 .. seealso:: :py:func:`valueAsString`
 
@@ -343,8 +343,8 @@ Calculates the current value of the property and interprets it as a string.
 :param context: QgsExpressionContext to evaluate the property for.
 :param defaultString: default string to return if the property cannot be calculated as a string
 
-:return: value parsed to string
-         ok:  if specified, will be set to true if conversion was successful
+:return: - value parsed to string
+         - ok:  if specified, will be set to true if conversion was successful
 
 .. seealso:: :py:func:`value`
 
@@ -364,8 +364,8 @@ Calculates the current value of the property and interprets it as a color.
 :param context: QgsExpressionContext to evaluate the property for.
 :param defaultColor: default color to return if the property cannot be calculated as a color
 
-:return: value parsed to color
-         ok:  if specified, will be set to true if conversion was successful
+:return: - value parsed to color
+         - ok:  if specified, will be set to true if conversion was successful
 
 .. seealso:: :py:func:`value`
 
@@ -385,8 +385,8 @@ Calculates the current value of the property and interprets it as a double.
 :param context: QgsExpressionContext to evaluate the property for.
 :param defaultValue: default double to return if the property cannot be calculated as a double
 
-:return: value parsed to double
-         ok:  if specified, will be set to true if conversion was successful
+:return: - value parsed to double
+         - ok:  if specified, will be set to true if conversion was successful
 
 .. seealso:: :py:func:`value`
 
@@ -406,8 +406,8 @@ Calculates the current value of the property and interprets it as an integer.
 :param context: QgsExpressionContext to evaluate the property for.
 :param defaultValue: default integer to return if the property cannot be calculated as an integer
 
-:return: value parsed to integer
-         ok:  if specified, will be set to true if conversion was successful
+:return: - value parsed to integer
+         - ok:  if specified, will be set to true if conversion was successful
 
 .. seealso:: :py:func:`value`
 
@@ -427,8 +427,8 @@ Calculates the current value of the property and interprets it as an boolean.
 :param context: QgsExpressionContext to evaluate the property for.
 :param defaultValue: default boolean to return if the property cannot be calculated as an boolean
 
-:return: value parsed to boolean
-         ok:  if specified, will be set to true if conversion was successful
+:return: - value parsed to boolean
+         - ok:  if specified, will be set to true if conversion was successful
 
 .. seealso:: :py:func:`value`
 
diff --git a/python/core/auto_generated/qgspropertycollection.sip.in b/python/core/auto_generated/qgspropertycollection.sip.in
index be1ccd9bf642..7d4c83981446 100644
--- a/python/core/auto_generated/qgspropertycollection.sip.in
+++ b/python/core/auto_generated/qgspropertycollection.sip.in
@@ -118,8 +118,8 @@ Calculates the current value of the property with the specified key and interpre
 :param context: QgsExpressionContext to evaluate the property for.
 :param defaultString: default string to return if the property cannot be calculated as a string
 
-:return: value parsed to string
-         ok:  if specified, will be set to true if conversion was successful
+:return: - value parsed to string
+         - ok:  if specified, will be set to true if conversion was successful
 
 .. seealso:: :py:func:`value`
 
@@ -141,8 +141,8 @@ Calculates the current value of the property with the specified key and interpre
 :param context: QgsExpressionContext to evaluate the property for.
 :param defaultColor: default color to return if the property cannot be calculated as a color
 
-:return: value parsed to color
-         ok:  if specified, will be set to true if conversion was successful
+:return: - value parsed to color
+         - ok:  if specified, will be set to true if conversion was successful
 
 .. seealso:: :py:func:`value`
 
@@ -164,8 +164,8 @@ Calculates the current value of the property with the specified key and interpre
 :param context: QgsExpressionContext to evaluate the property for.
 :param defaultValue: default double to return if the property cannot be calculated as a double
 
-:return: value parsed to double
-         ok:  if specified, will be set to true if conversion was successful
+:return: - value parsed to double
+         - ok:  if specified, will be set to true if conversion was successful
 
 .. seealso:: :py:func:`value`
 
@@ -187,8 +187,8 @@ Calculates the current value of the property with the specified key and interpre
 :param context: QgsExpressionContext to evaluate the property for.
 :param defaultValue: default integer to return if the property cannot be calculated as a integer
 
-:return: value parsed to integer
-         ok:  if specified, will be set to true if conversion was successful
+:return: - value parsed to integer
+         - ok:  if specified, will be set to true if conversion was successful
 
 .. seealso:: :py:func:`value`
 
@@ -210,8 +210,8 @@ Calculates the current value of the property with the specified key and interpre
 :param context: QgsExpressionContext to evaluate the property for.
 :param defaultValue: default boolean to return if the property cannot be calculated as a boolean
 
-:return: value parsed to bool
-         ok:  if specified, will be set to true if conversion was successful
+:return: - value parsed to bool
+         - ok:  if specified, will be set to true if conversion was successful
 
 .. seealso:: :py:func:`value`
 
diff --git a/python/core/auto_generated/qgspropertytransformer.sip.in b/python/core/auto_generated/qgspropertytransformer.sip.in
index 4299161471d9..4510b6aaa987 100644
--- a/python/core/auto_generated/qgspropertytransformer.sip.in
+++ b/python/core/auto_generated/qgspropertytransformer.sip.in
@@ -299,8 +299,8 @@ Attempts to parse an expression into a corresponding property transformer.
                   to the property transformer. This will be set to an
                   empty string if an expression is the transformer input.
 
-:return: corresponding property transformer, or None if expression could not
-         baseExpression:  will be set to the component of the source expression which is used to calculate the input to the property transformer. This will be set to an empty string if a field reference is the transformer input.
+:return: - corresponding property transformer, or None if expression could not
+         - baseExpression:  will be set to the component of the source expression which is used to calculate the input to the property transformer. This will be set to an empty string if a field reference is the transformer input.
          be parsed to a transformer.
 %End
 
@@ -366,8 +366,8 @@ Attempts to parse an expression into a corresponding :py:class:`QgsSizeScaleTran
                   to the property transformer. This will be set to an
                   empty string if an expression is the transformer input.
 
-:return: corresponding :py:class:`QgsSizeScaleTransformer`, or None if expression could not
-         baseExpression:  will be set to the component of the source expression which is used to calculate the input to the property transformer. This will be set to an empty string if a field reference is the transformer input.
+:return: - corresponding :py:class:`QgsSizeScaleTransformer`, or None if expression could not
+         - baseExpression:  will be set to the component of the source expression which is used to calculate the input to the property transformer. This will be set to an empty string if a field reference is the transformer input.
          be parsed to a size scale transformer.
 %End
 
@@ -513,8 +513,8 @@ Attempts to parse an expression into a corresponding QgsSizeScaleTransformer.
                   to the property transformer. This will be set to an
                   empty string if an expression is the transformer input.
 
-:return: corresponding QgsSizeScaleTransformer, or None if expression could not
-         baseExpression:  will be set to the component of the source expression which is used to calculate the input to the property transformer. This will be set to an empty string if a field reference is the transformer input.
+:return: - corresponding QgsSizeScaleTransformer, or None if expression could not
+         - baseExpression:  will be set to the component of the source expression which is used to calculate the input to the property transformer. This will be set to an empty string if a field reference is the transformer input.
          be parsed to a size scale transformer.
 %End
 
diff --git a/python/core/auto_generated/qgstransaction.sip.in b/python/core/auto_generated/qgstransaction.sip.in
index 266445954169..0d505920e9fe 100644
--- a/python/core/auto_generated/qgstransaction.sip.in
+++ b/python/core/auto_generated/qgstransaction.sip.in
@@ -92,8 +92,8 @@ Execute the ``sql`` string.
 :param isDirty: Flag to indicate if the underlying data will be modified
 :param name: Name of the transaction ( only used if `isDirty` is true)
 
-:return: true if everything is OK, false otherwise
-         error:  The error message
+:return: - true if everything is OK, false otherwise
+         - error:  The error message
 %End
 
     static bool supportsTransaction( const QgsVectorLayer *layer );
diff --git a/python/core/auto_generated/qgsunittypes.sip.in b/python/core/auto_generated/qgsunittypes.sip.in
index d82fd4764b68..5cd879f9f74c 100644
--- a/python/core/auto_generated/qgsunittypes.sip.in
+++ b/python/core/auto_generated/qgsunittypes.sip.in
@@ -153,8 +153,8 @@ Decodes a distance unit from a string.
 
 :param string: string to decode
 
-:return: decoded units
-         ok:  optional boolean, will be set to true if string was converted successfully
+:return: - decoded units
+         - ok:  optional boolean, will be set to true if string was converted successfully
 
 .. seealso:: :py:func:`encodeUnit`
 %End
@@ -185,6 +185,9 @@ Converts a translated string to a distance unit.
 
 :param string: string representing a distance unit
 
+:return: - the distance unit
+         - ok:  optional boolean, will be set to true if string was converted successfully
+
 .. seealso:: :py:func:`toString`
 %End
 
@@ -221,8 +224,8 @@ Decodes an areal unit from a string.
 
 :param string: string to decode
 
-:return: decoded units
-         ok:  optional boolean, will be set to true if string was converted successfully
+:return: - decoded units
+         - ok:  optional boolean, will be set to true if string was converted successfully
 
 .. seealso:: :py:func:`encodeUnit`
 %End
@@ -253,6 +256,9 @@ Converts a translated string to an areal unit.
 
 :param string: string representing an areal unit
 
+:return: - the area unit
+         - ok:  optional boolean, will be set to true if string was converted successfully
+
 .. seealso:: :py:func:`toString`
 %End
 
@@ -293,8 +299,8 @@ Decodes an angular unit from a string.
 
 :param string: string to decode
 
-:return: decoded units
-         ok:  optional boolean, will be set to true if string was converted successfully
+:return: - decoded units
+         - ok:  optional boolean, will be set to true if string was converted successfully
 
 .. seealso:: :py:func:`encodeUnit`
 %End
@@ -402,8 +408,8 @@ Decodes a render unit from a string.
 
 :param string: string to decode
 
-:return: decoded units
-         ok:  optional boolean, will be set to true if string was converted successfully
+:return: - decoded units
+         - ok:  optional boolean, will be set to true if string was converted successfully
 
 .. seealso:: :py:func:`encodeUnit`
 %End
@@ -436,8 +442,8 @@ Decodes a layout unit from a string.
 
 :param string: string to decode
 
-:return: decoded units
-         ok:  optional boolean, will be set to true if string was converted successfully
+:return: - decoded units
+         - ok:  optional boolean, will be set to true if string was converted successfully
 
 .. seealso:: :py:func:`encodeUnit`
 
diff --git a/python/core/auto_generated/qgsvectorlayer.sip.in b/python/core/auto_generated/qgsvectorlayer.sip.in
index 3027f446aa60..ffbb33d2e756 100644
--- a/python/core/auto_generated/qgsvectorlayer.sip.in
+++ b/python/core/auto_generated/qgsvectorlayer.sip.in
@@ -799,8 +799,8 @@ Lists all the style in db split into related to the layer and not related to
 :param names: the list in which will be stored the style names
 :param msgError:
 
-:return: the number of styles related to current layer
-         descriptions:  the list in which will be stored the style descriptions
+:return: - the number of styles related to current layer
+         - descriptions:  the list in which will be stored the style descriptions
 
 .. note::
 
@@ -818,8 +818,8 @@ 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
-         msgError:  reference to string that will be updated with any error messages
+:return: - true in case of success
+         - msgError:  reference to string that will be updated with any error messages
 
 .. versionadded:: 3.0
 %End
diff --git a/python/core/auto_generated/qgsvectorlayerjoinbuffer.sip.in b/python/core/auto_generated/qgsvectorlayerjoinbuffer.sip.in
index 6063b650ce2b..799d7f880170 100644
--- a/python/core/auto_generated/qgsvectorlayerjoinbuffer.sip.in
+++ b/python/core/auto_generated/qgsvectorlayerjoinbuffer.sip.in
@@ -85,6 +85,9 @@ Finds the vector join for a layer field index.
 
 :param index: this layers attribute index
 :param fields: fields of the vector layer (including joined fields)
+
+:return: - the vector layer join info
+         - sourceFieldIndex:  Output: field's index in source layer
 %End
 
     int joinedFieldsOffset( const QgsVectorLayerJoinInfo *info, const QgsFields &fields );
diff --git a/python/core/auto_generated/qgsvectorlayertools.sip.in b/python/core/auto_generated/qgsvectorlayertools.sip.in
index f58958791538..91bbf7ee4f59 100644
--- a/python/core/auto_generated/qgsvectorlayertools.sip.in
+++ b/python/core/auto_generated/qgsvectorlayertools.sip.in
@@ -35,8 +35,8 @@ This method should/will be called, whenever a new feature will be added to the l
 :param defaultValues: Default values for the feature to add
 :param defaultGeometry: A default geometry to add to the feature
 
-:return: True in case of success, False if the operation failed/was aborted
-         feature:  Updated feature after adding will be written back to this
+:return: - True in case of success, False if the operation failed/was aborted
+         - feature:  Updated feature after adding will be written back to this
 
 TODO QGIS 3: remove const qualifier
 %End
@@ -87,8 +87,8 @@ Copy and move features with defined translation.
 :param dx: The translation on x
 :param dy: The translation on y
 
-:return: True if all features could be copied.
-         errorMsg:  If given, it will contain the error message
+:return: - True if all features could be copied.
+         - errorMsg:  If given, it will contain the error message
 
 TODO QGIS 3: remove const qualifier
 %End
diff --git a/python/core/auto_generated/qgsziputils.sip.in b/python/core/auto_generated/qgsziputils.sip.in
index ef972c39f21a..3d3a18362fd2 100644
--- a/python/core/auto_generated/qgsziputils.sip.in
+++ b/python/core/auto_generated/qgsziputils.sip.in
@@ -27,13 +27,15 @@ extension, false otherwise.
 
   bool unzip( const QString &zip, const QString &dir, QStringList &files /Out/ );
 %Docstring
-Unzip a zip file in an output directory. An error is returned if the zip
-filename does not exist, the output directory does not exist or is
-not writable.
+Unzip a zip file in an output directory.
 
 :param zip: The zip filename
 :param dir: The output directory
 
+:return: - false if the zip filename does not exist, the output directory
+         - files:  The absolute path of unzipped files
+         does not exist or is not writable.
+
 .. versionadded:: 3.0
 %End
 
diff --git a/python/core/auto_generated/raster/qgsrastershader.sip.in b/python/core/auto_generated/raster/qgsrastershader.sip.in
index 58ff880f1899..1810d99a5343 100644
--- a/python/core/auto_generated/raster/qgsrastershader.sip.in
+++ b/python/core/auto_generated/raster/qgsrastershader.sip.in
@@ -59,8 +59,8 @@ Generates a new RGBA value based on one input ``value``.
 :param returnGreenValue: The green component of the new RGBA value
 :param returnBlueValue: The blue component of the new RGBA value
 
-:return: True if the return values are valid otherwise false
-         returnAlpha:  The alpha component of the new RGBA value
+:return: - True if the return values are valid otherwise false
+         - returnAlpha:  The alpha component of the new RGBA value
 %End
 
     bool shade( double redValue,
@@ -82,8 +82,8 @@ Generates a new RGBA value based on an original RGBA value.
 :param returnGreenValue: The green component of the new RGBA value
 :param returnBlueValue: The blue component of the new RGBA value
 
-:return: True if the return values are valid otherwise false
-         returnAlpha:  The alpha component of the new RGBA value
+:return: - True if the return values are valid otherwise false
+         - returnAlpha:  The alpha component of the new RGBA value
 %End
 
     void setRasterShaderFunction( QgsRasterShaderFunction *function /Transfer/ );
diff --git a/python/core/auto_generated/raster/qgsrastershaderfunction.sip.in b/python/core/auto_generated/raster/qgsrastershaderfunction.sip.in
index 8216f371633a..e3c64df8e4be 100644
--- a/python/core/auto_generated/raster/qgsrastershaderfunction.sip.in
+++ b/python/core/auto_generated/raster/qgsrastershaderfunction.sip.in
@@ -63,8 +63,8 @@ Generates an new RGBA value based on one input ``value``.
 :param returnGreenValue: The green component of the new RGBA value
 :param returnBlueValue: The blue component of the new RGBA value
 
-:return: True if the return values are valid otherwise false
-         returnAlpha:  The alpha component of the new RGBA value
+:return: - True if the return values are valid otherwise false
+         - returnAlpha:  The alpha component of the new RGBA value
 %End
 
     virtual bool shade( double redValue,
@@ -86,8 +86,8 @@ Generates an new RGBA value based on an original RGBA value.
 :param returnGreenValue: The green component of the new RGBA value
 :param returnBlueValue: The blue component of the new RGBA value
 
-:return: True if the return values are valid otherwise false
-         returnAlpha:  The alpha component of the new RGBA value
+:return: - True if the return values are valid otherwise false
+         - returnAlpha:  The alpha component of the new RGBA value
 %End
 
     double minimumMaximumRange() const;
diff --git a/python/gui/auto_generated/editorwidgets/core/qgseditorwidgetautoconf.sip.in b/python/gui/auto_generated/editorwidgets/core/qgseditorwidgetautoconf.sip.in
index f6a6cd2241eb..29c91918598b 100644
--- a/python/gui/auto_generated/editorwidgets/core/qgseditorwidgetautoconf.sip.in
+++ b/python/gui/auto_generated/editorwidgets/core/qgseditorwidgetautoconf.sip.in
@@ -33,8 +33,8 @@ Typical scores are:
 :param vl: The vector layer for which this widget will be created
 :param fieldName: The field name on the specified layer for which this widget will be created
 
-:return: and integer value rating how good is the setup provided by this plugin.
-         score:  Where the score is returned (default to 0)
+:return: - and integer value rating how good is the setup provided by this plugin.
+         - score:  Where the score is returned (default to 0)
 %End
 
 };
diff --git a/python/gui/auto_generated/qgsexpressionlineedit.sip.in b/python/gui/auto_generated/qgsexpressionlineedit.sip.in
index d23e33efaf15..187c0e6826f9 100644
--- a/python/gui/auto_generated/qgsexpressionlineedit.sip.in
+++ b/python/gui/auto_generated/qgsexpressionlineedit.sip.in
@@ -110,8 +110,11 @@ Returns the current expression shown in the widget.
 
     bool isValidExpression( QString *expressionError /Out/ = 0 ) const;
 %Docstring
-Returns true if the current expression is valid.
+Determines if the current expression is valid.
 
+
+:return: - true if the current expression is valid.
+         - expressionError:  will be set to any generated error message if specified
 %End
 
     void registerExpressionContextGenerator( const QgsExpressionContextGenerator *generator );
diff --git a/python/server/auto_generated/qgsserverexception.sip.in b/python/server/auto_generated/qgsserverexception.sip.in
index 120e7424b4dd..50a18abb59cb 100644
--- a/python/server/auto_generated/qgsserverexception.sip.in
+++ b/python/server/auto_generated/qgsserverexception.sip.in
@@ -39,8 +39,8 @@ Constructor
 Format the exception for sending to client
 
 
-:return: QByteArray the fermatted response.
-         responseFormat:  QString to store the content type of the response format.
+:return: - QByteArray the fermatted response.
+         - responseFormat:  QString to store the content type of the response format.
 
 The defaolt implementation return text/xml format.
 %End