Add help string for parameters in Processing

qgis · Sep 21, 2020 · 6076950 · 6076950
1 parent d5f2711
commit 6076950
Show file tree

Hide file tree

Showing 7 changed files with 58 additions and 8 deletions.
diff --git a/python/core/auto_generated/processing/qgsprocessingparameters.sip.in b/python/core/auto_generated/processing/qgsprocessingparameters.sip.in
@@ -319,7 +319,7 @@ their acceptable ranges, defaults, etc.
 
 
     QgsProcessingParameterDefinition( const QString &name, const QString &description = QString(), const QVariant &defaultValue = QVariant(),
-                                      bool optional = false );
+                                      bool optional = false, const QString &help = QString() );
 %Docstring
 Constructor for QgsProcessingParameterDefinition.
 %End
@@ -373,6 +373,24 @@ Sets the ``description`` for the parameter. This is the user-visible string
 used to identify this parameter.
 
 .. seealso:: :py:func:`description`
+%End
+
+    QString help() const;
+%Docstring
+Returns the help for the parameter.
+
+.. seealso:: :py:func:`setHelp`
+
+.. versionadded:: 3.16
+%End
+
+    void setHelp( const QString &help );
+%Docstring
+Sets the ``help`` for the parameter.
+
+.. seealso:: :py:func:`help`
+
+.. versionadded:: 3.16
 %End
 
     QVariant defaultValue() const;
@@ -624,6 +642,7 @@ The ``variables`` list should contain the variable names only, without the usual
 
 
 
+
 };
 
 QFlags<QgsProcessingParameterDefinition::Flag> operator|(QgsProcessingParameterDefinition::Flag f1, QFlags<QgsProcessingParameterDefinition::Flag> f2);

diff --git a/python/plugins/processing/tools/general.py b/python/plugins/processing/tools/general.py
@@ -56,6 +56,8 @@ def algorithmHelp(id):
         print('----------------')
         for p in alg.parameterDefinitions():
             print('\n{}: {}'.format(p.name(), p.description()))
+            if p.help():
+                print('\n\t{}'.format(p.help()))
 
             print('\n\tParameter type:\t{}'.format(p.__class__.__name__))
 

diff --git a/src/analysis/processing/qgsalgorithmbuffer.cpp b/src/analysis/processing/qgsalgorithmbuffer.cpp
@@ -55,8 +55,9 @@ void QgsBufferAlgorithm::initAlgorithm( const QVariantMap & )
   bufferParam->setDynamicPropertyDefinition( QgsPropertyDefinition( QStringLiteral( "Distance" ), QObject::tr( "Buffer distance" ), QgsPropertyDefinition::Double ) );
   bufferParam->setDynamicLayerParameterName( QStringLiteral( "INPUT" ) );
   addParameter( bufferParam.release() );
-  addParameter( new QgsProcessingParameterNumber( QStringLiteral( "SEGMENTS" ), QObject::tr( "Segments" ), QgsProcessingParameterNumber::Integer, 5, false, 1 ) );
-
+  auto segmentParam = qgis::make_unique < QgsProcessingParameterNumber >( QStringLiteral( "SEGMENTS" ), QObject::tr( "Segments" ), QgsProcessingParameterNumber::Integer, 5, false, 1 );
+  segmentParam->setHelp( QObject::tr( "The segments parameter controls the number of line segments to use to approximate a quarter circle when creating rounded offsets." ) );
+  addParameter( segmentParam.release() );
   addParameter( new QgsProcessingParameterEnum( QStringLiteral( "END_CAP_STYLE" ), QObject::tr( "End cap style" ), QStringList() << QObject::tr( "Round" ) << QObject::tr( "Flat" ) << QObject::tr( "Square" ), false, 0 ) );
   addParameter( new QgsProcessingParameterEnum( QStringLiteral( "JOIN_STYLE" ), QObject::tr( "Join style" ), QStringList() << QObject::tr( "Round" ) << QObject::tr( "Miter" ) << QObject::tr( "Bevel" ), false, 0 ) );
   addParameter( new QgsProcessingParameterNumber( QStringLiteral( "MITER_LIMIT" ), QObject::tr( "Miter limit" ), QgsProcessingParameterNumber::Double, 2, false, 1 ) );

diff --git a/src/core/processing/qgsprocessingparameters.cpp b/src/core/processing/qgsprocessingparameters.cpp
@@ -2289,9 +2289,10 @@ bool QgsProcessingParameters::parseScriptCodeParameterOptions( const QString &co
 // QgsProcessingParameterDefinition
 //
 
-QgsProcessingParameterDefinition::QgsProcessingParameterDefinition( const QString &name, const QString &description, const QVariant &defaultValue, bool optional )
+QgsProcessingParameterDefinition::QgsProcessingParameterDefinition( const QString &name, const QString &description, const QVariant &defaultValue, bool optional, const QString &help )
   : mName( name )
   , mDescription( description )
+  , mHelp( help )
   , mDefault( defaultValue )
   , mFlags( optional ? FlagOptional : 0 )
 {}
@@ -2387,9 +2388,13 @@ QgsProcessingProvider *QgsProcessingParameterDefinition::provider() const
 
 QString QgsProcessingParameterDefinition::toolTip() const
 {
-  return QStringLiteral( "<p><b>%1</b></p><p>%2</p>" ).arg(
-           description(),
-           QObject::tr( "Python identifier: ‘%1’" ).arg( QStringLiteral( "<i>%1</i>" ).arg( name() ) ) );
+  QString text = QStringLiteral( "<p><b>%1</b></p>" ).arg( description() );
+  if ( !help().isEmpty() )
+  {
+    text += QStringLiteral( "<p>%1</p>" ).arg( help() );
+  }
+  text += QStringLiteral( "<p>%1</p>" ).arg( QObject::tr( "Python identifier: ‘%1’" ).arg( QStringLiteral( "<i>%1</i>" ).arg( name() ) ) );
+  return text;
 }
 
 QgsProcessingParameterBoolean::QgsProcessingParameterBoolean( const QString &name, const QString &description, const QVariant &defaultValue, bool optional )

diff --git a/src/core/processing/qgsprocessingparameters.h b/src/core/processing/qgsprocessingparameters.h
@@ -431,7 +431,7 @@ class CORE_EXPORT QgsProcessingParameterDefinition
      * Constructor for QgsProcessingParameterDefinition.
      */
     QgsProcessingParameterDefinition( const QString &name, const QString &description = QString(), const QVariant &defaultValue = QVariant(),
-                                      bool optional = false );
+                                      bool optional = false, const QString &help = QString() );
 
     virtual ~QgsProcessingParameterDefinition() = default;
 
@@ -480,6 +480,20 @@ class CORE_EXPORT QgsProcessingParameterDefinition
      */
     void setDescription( const QString &description ) { mDescription = description; }
 
+    /**
+     * Returns the help for the parameter.
+     * \see setHelp()
+     * \since QGIS 3.16
+     */
+    QString help() const { return mHelp; }
+
+    /**
+     * Sets the \a help for the parameter.
+     * \see help()
+     * \since QGIS 3.16
+     */
+    void setHelp( const QString &help ) { mHelp = help; }
+
     /**
      * Returns the default value for the parameter.
      * \see setDefaultValue()
@@ -701,6 +715,9 @@ class CORE_EXPORT QgsProcessingParameterDefinition
     //! Parameter description
     QString mDescription;
 
+    //! Parameter help
+    QString mHelp;
+
     //! Default value for parameter
     QVariant mDefault;
 

diff --git a/src/process/qgsprocess.cpp b/src/process/qgsprocess.cpp
@@ -395,6 +395,10 @@ int QgsProcessingExec::showAlgorithmHelp( const QString &id )
       continue;
 
     std::cout << QStringLiteral( "%1: %2\n" ).arg( p->name(), p->description() ).toLocal8Bit().constData();
+    if ( ! p->help().isEmpty() )
+    {
+      std::cout << QStringLiteral( "\t%1\n" ).arg( p->help() ).toLocal8Bit().constData();
+    }
     std::cout << QStringLiteral( "\tArgument type:\t%1\n" ).arg( p->type() ).toLocal8Bit().constData();
 
     if ( p->type() == QgsProcessingParameterEnum::typeName() )

diff --git a/tests/src/gui/testprocessinggui.cpp b/tests/src/gui/testprocessinggui.cpp
@@ -6476,11 +6476,13 @@ void TestProcessingGui::paramConfigWidget()
 
   // using a parameter definition as initial values
   def->setDescription( QStringLiteral( "test desc" ) );
+  def->setHelp( QStringLiteral( "test help" ) );
   def->setFlags( QgsProcessingParameterDefinition::FlagOptional );
   widget = qgis::make_unique< QgsProcessingParameterDefinitionWidget >( QStringLiteral( "string" ), context, widgetContext, def.get() );
   def.reset( widget->createParameter( QStringLiteral( "param_name" ) ) );
   QCOMPARE( def->name(), QStringLiteral( "param_name" ) );
   QCOMPARE( def->description(), QStringLiteral( "test desc" ) );
+  QCOMPARE( def->help(), QStringLiteral( "test help" ) );
   QVERIFY( def->flags() & QgsProcessingParameterDefinition::FlagOptional );
   QVERIFY( !( def->flags() & QgsProcessingParameterDefinition::FlagAdvanced ) );
   def->setFlags( QgsProcessingParameterDefinition::FlagAdvanced );