expression help: support optional parameters and defaults

Author: jef-n

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": [
     {

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": [
     {

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(

src/core/expression/qgsexpression.cpp

@@ -575,20 +575,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 )
@@ -600,6 +613,11 @@ QString QgsExpression::helpText( QString name )
       }
 
       helpContents += QLatin1String( "</code>" );
+
+      if ( hasOptionalArgs )
+      {
+        helpContents += QLatin1String( "<br/><br/>" ) + tr( "[ ] marks optional components" );
+      }
     }
 
     if ( !v.mArguments.isEmpty() )