expression help: support optional parameters and defaults

jef-n · jef-n · commit ca3d2c0dfcd2 · 2018-05-10T20:22:04.000+02:00
(cherry picked from commit 968b50f)
diff --git a/resources/function_help/json/closest_point b/resources/function_help/json/closest_point
@@ -1,10 +1,10 @@
 {
   "name": "closest_point",
   "type": "function",
-  "description": "Returns the point on geometry 1 that is closest to geometry 2.",
+  "description": "Returns the point on geometry1 that is closest to geometry2.",
   "arguments": [
-    {"arg":"geometry 1","description":"geometry to find closest point on"},
-    {"arg":"geometry 2","description":"geometry to find closest point to"}
+    {"arg":"geometry1","description":"geometry to find closest point on"},
+    {"arg":"geometry2","description":"geometry to find closest point to"}
   ],
   "examples": [
     {
diff --git a/resources/function_help/json/shortest_line b/resources/function_help/json/shortest_line
@@ -1,10 +1,10 @@
 {
   "name": "shortest_line",
   "type": "function",
-  "description": "Returns the shortest line joining geometry 1 to geometry 2. The resultant line will start at geometry 1 and end at geometry 2.",
+  "description": "Returns the shortest line joining geometry1 to geometry2. The resultant line will start at geometry1 and end at geometry2.",
   "arguments": [
-    {"arg":"geometry 1","description":"geometry to find shortest line from"},
-    {"arg":"geometry 2","description":"geometry to find shortest line to"}
+    {"arg":"geometry1","description":"geometry to find shortest line from"},
+    {"arg":"geometry2","description":"geometry to find shortest line to"}
   ],
   "examples": [
     {
diff --git a/scripts/process_function_template.py b/scripts/process_function_template.py
@@ -87,13 +87,14 @@ def quote(v):
 
         if 'arguments' in v:
             for a in v['arguments']:
-                cpp.write("\n              << HelpArg( \"{0}\", tr( \"{1}\" ), {2}, {3} )".format(
+                cpp.write("\n              << HelpArg( \"{0}\", tr( \"{1}\" ), {2}, {3}, {4}, \"{5}\" )".format(
                     a['arg'],
                     a.get('description', ''),
                     "true" if a.get('descOnly', False) else "false",
                     "true" if a.get('syntaxOnly', False) else "false",
                     "true" if a.get('optional', False) else "false",
-                    a.get('default', ''))
+                    a.get('default', '')
+                )
                 )
 
         cpp.write(",\n          /* variableLenArguments */ {0}".format(
diff --git a/src/core/expression/qgsexpression.cpp b/src/core/expression/qgsexpression.cpp
@@ -548,20 +548,33 @@ QString QgsExpression::helpText( QString name )
     {
       helpContents += QStringLiteral( "<code><span class=\"functionname\">%1</span>" ).arg( name );
 
+      bool hasOptionalArgs = false;
+
       if ( f.mType == tr( "function" ) && ( f.mName[0] != '$' || !v.mArguments.isEmpty() || v.mVariableLenArguments ) )
       {
         helpContents += '(';
 
         QString delim;
         for ( const HelpArg &a : qgis::as_const( v.mArguments ) )
         {
-          helpContents += delim;
-          delim = QStringLiteral( ", " );
           if ( !a.mDescOnly )
           {
-            helpContents += QStringLiteral( "<span class=\"argument %1\">%2%3</span>" ).arg( a.mOptional ? QStringLiteral( "optional" ) : QStringLiteral( "" ), a.mArg,
-                            a.mDefaultVal.isEmpty() ? QLatin1String( "" ) : '=' + a.mDefaultVal );
+            if ( a.mOptional )
+            {
+              hasOptionalArgs = true;
+              helpContents += QStringLiteral( "[" );
+            }
+
+            helpContents += delim;
+            helpContents += QStringLiteral( "<span class=\"argument\">%2%3</span>" ).arg(
+                              a.mArg,
+                              a.mDefaultVal.isEmpty() ? QLatin1String( "" ) : '=' + a.mDefaultVal
+                            );
+
+            if ( a.mOptional )
+              helpContents += QStringLiteral( "]" );
           }
+          delim = QStringLiteral( "," );
         }
 
         if ( v.mVariableLenArguments )
@@ -573,6 +586,11 @@ QString QgsExpression::helpText( QString name )
       }
 
       helpContents += QLatin1String( "</code>" );
+
+      if ( hasOptionalArgs )
+      {
+        helpContents += QLatin1String( "<br/><br/>" ) + tr( "[ ] marks optional components" );
+      }
     }
 
     if ( !v.mArguments.isEmpty() )

Original file line number	Diff line number	Diff line change
`@@ -1,10 +1,10 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "closest_point",`
`3`	`3`	`"type": "function",`
`4`		`- "description": "Returns the point on geometry 1 that is closest to geometry 2.",`
	`4`	`+ "description": "Returns the point on geometry1 that is closest to geometry2.",`
`5`	`5`	`"arguments": [`
`6`		`- {"arg":"geometry 1","description":"geometry to find closest point on"},`
`7`		`- {"arg":"geometry 2","description":"geometry to find closest point to"}`
	`6`	`+ {"arg":"geometry1","description":"geometry to find closest point on"},`
	`7`	`+ {"arg":"geometry2","description":"geometry to find closest point to"}`
`8`	`8`	`],`
`9`	`9`	`"examples": [`
`10`	`10`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,10 +1,10 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "shortest_line",`
`3`	`3`	`"type": "function",`
`4`		`- "description": "Returns the shortest line joining geometry 1 to geometry 2. The resultant line will start at geometry 1 and end at geometry 2.",`
	`4`	`+ "description": "Returns the shortest line joining geometry1 to geometry2. The resultant line will start at geometry1 and end at geometry2.",`
`5`	`5`	`"arguments": [`
`6`		`- {"arg":"geometry 1","description":"geometry to find shortest line from"},`
`7`		`- {"arg":"geometry 2","description":"geometry to find shortest line to"}`
	`6`	`+ {"arg":"geometry1","description":"geometry to find shortest line from"},`
	`7`	`+ {"arg":"geometry2","description":"geometry to find shortest line to"}`
`8`	`8`	`],`
`9`	`9`	`"examples": [`
`10`	`10`	`{`
Original file line number	Diff line number	Diff line change
`@@ -548,20 +548,33 @@ QString QgsExpression::helpText( QString name )`
`548`	`548`	`{`
`549`	`549`	`helpContents += QStringLiteral( "<code><span class=\"functionname\">%1</span>" ).arg( name );`
`550`	`550`
	`551`	`+ bool hasOptionalArgs = false;`
	`552`	`+`
`551`	`553`	`if ( f.mType == tr( "function" ) && ( f.mName[0] != '$' \|\| !v.mArguments.isEmpty() \|\| v.mVariableLenArguments ) )`
`552`	`554`	`{`
`553`	`555`	`helpContents += '(';`
`554`	`556`
`555`	`557`	`QString delim;`
`556`	`558`	`for ( const HelpArg &a : qgis::as_const( v.mArguments ) )`
`557`	`559`	`{`
`558`		`- helpContents += delim;`
`559`		`- delim = QStringLiteral( ", " );`
`560`	`560`	`if ( !a.mDescOnly )`
`561`	`561`	`{`
`562`		`- helpContents += QStringLiteral( "<span class=\"argument %1\">%2%3</span>" ).arg( a.mOptional ? QStringLiteral( "optional" ) : QStringLiteral( "" ), a.mArg,`
`563`		`- a.mDefaultVal.isEmpty() ? QLatin1String( "" ) : '=' + a.mDefaultVal );`
	`562`	`+ if ( a.mOptional )`
	`563`	`+ {`
	`564`	`+ hasOptionalArgs = true;`
	`565`	`+ helpContents += QStringLiteral( "[" );`
	`566`	`+ }`
	`567`	`+`
	`568`	`+ helpContents += delim;`
	`569`	`+ helpContents += QStringLiteral( "<span class=\"argument\">%2%3</span>" ).arg(`
	`570`	`+ a.mArg,`
	`571`	`+ a.mDefaultVal.isEmpty() ? QLatin1String( "" ) : '=' + a.mDefaultVal`
	`572`	`+ );`
	`573`	`+`
	`574`	`+ if ( a.mOptional )`
	`575`	`+ helpContents += QStringLiteral( "]" );`
`564`	`576`	`}`
	`577`	`+ delim = QStringLiteral( "," );`
`565`	`578`	`}`
`566`	`579`
`567`	`580`	`if ( v.mVariableLenArguments )`
`@@ -573,6 +586,11 @@ QString QgsExpression::helpText( QString name )`
`573`	`586`	`}`
`574`	`587`
`575`	`588`	`helpContents += QLatin1String( "</code>" );`
	`589`	`+`
	`590`	`+ if ( hasOptionalArgs )`
	`591`	`+ {`
	`592`	`+ helpContents += QLatin1String( "<br/><br/>" ) + tr( "[ ] marks optional components" );`
	`593`	`+ }`
`576`	`594`	`}`
`577`	`595`
`578`	`596`	`if ( !v.mArguments.isEmpty() )`