Document parameters in tooltips

CHANGELOG.md

@@ -40,6 +40,9 @@ RELEASING:
 14. Create new release in GitHub with tag version and release title of `vX.X.X`
  -->
 
+# Unreleased
+
+- Add tooltip hints in processing algorithms ([#196](https://github.com/GIScience/orstools-qgis-plugin/issues/196))
 
 ## [1.7.1] - 2024-01-15
 

ORStools/proc/base_processing_algorithm.py

@@ -116,35 +116,46 @@ def provider_parameter(self) -> QgsProcessingParameterEnum:
         Parameter definition for provider, used in all child classes
         """
         providers = [provider["name"] for provider in configmanager.read_config()["providers"]]
-        return QgsProcessingParameterEnum(
+        parameter = QgsProcessingParameterEnum(
             self.IN_PROVIDER,
             self.tr("Provider", "ORSBaseProcessingAlgorithm"),
             providers,
             defaultValue=providers[0],
         )
 
+        self.setToolTip(parameter, "Select the provider that should be used.")
+
+        return parameter
+
     def profile_parameter(self) -> QgsProcessingParameterEnum:
         """
         Parameter definition for profile, used in all child classes
         """
-        return QgsProcessingParameterEnum(
+        parameter = QgsProcessingParameterEnum(
             self.IN_PROFILE,
             self.tr("Travel mode", "ORSBaseProcessingAlgorithm"),
             PROFILES,
             defaultValue=PROFILES[0],
         )
 
+        self.setToolTip(parameter, "Select a mode of travel.")
+
+        return parameter
+
     def output_parameter(self) -> QgsProcessingParameterFeatureSink:
         """
         Parameter definition for output, used in all child classes
         """
-        return QgsProcessingParameterFeatureSink(
+        parameter = QgsProcessingParameterFeatureSink(
             name=self.OUT,
             description=self.GROUP,
         )
+        self.setToolTip(parameter, "Select where the output should be saved.")
+
+        return parameter
 
     def option_parameters(self) -> [QgsProcessingParameterDefinition]:
-        return [
+        parameters = [
             QgsProcessingParameterEnum(
                 self.IN_AVOID_FEATS,
                 self.tr("Features to avoid", "ORSBaseProcessingAlgorithm"),
@@ -177,6 +188,13 @@ def option_parameters(self) -> [QgsProcessingParameterDefinition]:
             ),
         ]
 
+        self.setToolTip(parameters[0], "Select features that should be avoided by the algorithm.")
+        self.setToolTip(parameters[1], "Select borders that should be avoided by the algorithm.")
+        self.setToolTip(parameters[2], "Select countries that should be avoided by the algorithm.")
+        self.setToolTip(parameters[3], "Select polygons that should be avoided by the algorithm.")
+
+        return parameters
+
     @classmethod
     def _get_ors_client_from_provider(
         cls, provider: str, feedback: QgsProcessingFeedback
@@ -245,3 +263,7 @@ def initAlgorithm(self, configuration):
     def tr(self, string, context=None):
         context = context or self.__class__.__name__
         return QCoreApplication.translate(context, string)
+
+    def setToolTip(self, parameter, text):
+        basic = parameter.toolTip()
+        parameter.toolTip = lambda: f"{basic}\n{text}"

ORStools/proc/directions_lines_proc.py

@@ -84,6 +84,19 @@ def __init__(self):
             ),
         ]
 
+        self.setToolTip(self.PARAMETERS[0], "LineString or MultiLineString layer.")
+        self.setToolTip(
+            self.PARAMETERS[1],
+            "Values will transfer to the output layer and can be used to join layers or group features afterwards.",
+        )
+        self.setToolTip(
+            self.PARAMETERS[2], "Dictates the cost. For longer routes don't use Shortest Path."
+        )
+        self.setToolTip(
+            self.PARAMETERS[3],
+            "You can optionally perform a Traveling Salesman on the waypoints of each MultiPoint feature. Enabling Traveling Salesman will erase all other advanced configuration and assume the preference to be fastest Advanced Parameters: see the documentation for descriptions.",
+        )
+
     def processAlgorithm(self, parameters, context, feedback):
         ors_client = self._get_ors_client_from_provider(parameters[self.IN_PROVIDER], feedback)
 

ORStools/proc/directions_points_layer_proc.py

@@ -92,6 +92,23 @@ def __init__(self):
             ),
         ]
 
+        self.setToolTip(self.PARAMETERS[0], "Point or MultiPoint layer.")
+        self.setToolTip(
+            self.PARAMETERS[1],
+            "Values will transfer to the output layer and can be used to join layers or group features afterwards.",
+        )
+        self.setToolTip(
+            self.PARAMETERS[2],
+            "Before running the algorithm points are sorted by the values of this field (Be aware of the field type! Text fields will be sorted like 1,13,2,D,a,x).",
+        )
+        self.setToolTip(
+            self.PARAMETERS[3], "Dictates the cost. For longer routes don't use Shortest Path."
+        )
+        self.setToolTip(
+            self.PARAMETERS[4],
+            "You can optionally perform a Traveling Salesman Optimization on the waypoints of each (Multi)Point feature. Enabling Traveling Salesman will erase all other advanced configuration and assume the preference to be fastest.",
+        )
+
     def processAlgorithm(self, parameters, context, feedback):
         ors_client = self._get_ors_client_from_provider(parameters[self.IN_PROVIDER], feedback)
 

ORStools/proc/directions_points_layers_proc.py

@@ -108,6 +108,31 @@ def __init__(self):
                 defaultValue=self.MODE_SELECTION[0],
             ),
         ]
+        self.setToolTip(self.PARAMETERS[0], "Only Point layers are allowed, not MultiPoint.")
+        self.setToolTip(
+            self.PARAMETERS[1],
+            "Values will transfer to the output layer and can be used to join layers or group features afterwards.",
+        )
+        self.setToolTip(
+            self.PARAMETERS[2],
+            "Before running the algorithm points are sorted by the values of this field (Be aware of the field type! Text fields will be sorted like 1,13,2,D,a,x)",
+        )
+        self.setToolTip(self.PARAMETERS[3], "Only Point layers are allowed, not MultiPoint.")
+        self.setToolTip(
+            self.PARAMETERS[4],
+            "Values will transfer to the output layer and can be used to join layers or group features afterwards.",
+        )
+        self.setToolTip(
+            self.PARAMETERS[5],
+            "Before running the algorithm points are sorted by the values of this field (Be aware of the field type! Text fields will be sorted like 1,13,2,D,a,x)",
+        )
+        self.setToolTip(
+            self.PARAMETERS[6], "Dictates the cost. For longer routes don't use Shortest Path."
+        )
+        self.setToolTip(
+            self.PARAMETERS[7],
+            "Either 'row-by-row' until one layers has no more features or 'all-by-all' for every feature combination",
+        )
 
     # TODO: preprocess parameters to options the range cleanup below:
     # https://www.qgis.org/pyqgis/master/core/Processing/QgsProcessingAlgorithm.html#qgis.core.QgsProcessingAlgorithm.preprocessParameters

ORStools/proc/isochrones_layer_proc.py

@@ -104,6 +104,24 @@ def __init__(self):
             ),
         ]
 
+        self.setToolTip(self.PARAMETERS[0], "Only Point layers are allowed, not MultiPoint.")
+        self.setToolTip(
+            self.PARAMETERS[1],
+            "Values will transfer to the output layer and can be used to join layers or group features afterwards.",
+        )
+        self.setToolTip(
+            self.PARAMETERS[3],
+            "Parameter needs to be a comma-separated list of integer values, no decimal points.",
+        )
+        self.setToolTip(
+            self.PARAMETERS[4],
+            "Applies a level of generalisation to the isochrone polygons generated as a smoothing_factor between 0 and 100.",
+        )
+        self.setToolTip(
+            self.PARAMETERS[5],
+            "Start treats the location(s) as starting point, destination as goal.",
+        )
+
     # Save some important references
     # TODO bad style, refactor
     isochrones = isochrones_core.Isochrones()

ORStools/proc/isochrones_point_proc.py

@@ -90,6 +90,20 @@ def __init__(self):
             ),
         ]
 
+        self.setToolTip(self.PARAMETERS[0], "Choose a Point from the map.")
+        self.setToolTip(
+            self.PARAMETERS[2],
+            "Parameter needs to be a comma-separated list of integer values, no decimal points.",
+        )
+        self.setToolTip(
+            self.PARAMETERS[3],
+            "Applies a level of generalisation to the isochrone polygons generated as a smoothing_factor between 0 and 100.",
+        )
+        self.setToolTip(
+            self.PARAMETERS[4],
+            "Start treats the location(s) as starting point, destination as goal.",
+        )
+
     # Save some important references
     # TODO bad style, refactor
     isochrones = isochrones_core.Isochrones()

ORStools/proc/matrix_proc.py

@@ -82,6 +82,17 @@ def __init__(self):
             ),
         ]
 
+        self.setToolTip(self.PARAMETERS[0], "Only Point layers are allowed, not MultiPoint.")
+        self.setToolTip(
+            self.PARAMETERS[1],
+            "Values will transfer to the output layer and can be used to join layers or group features afterwards.",
+        )
+        self.setToolTip(self.PARAMETERS[2], "Only Point layers are allowed, not MultiPoint.")
+        self.setToolTip(
+            self.PARAMETERS[3],
+            "Values will transfer to the output layer and can be used to join layers or group features afterwards.",
+        )
+
     def processAlgorithm(self, parameters, context, feedback):
         ors_client = self._get_ors_client_from_provider(parameters[self.IN_PROVIDER], feedback)