A new way of adding parameters that allows overriding inherited parameters (and sphinx auto documentation)

qcodes/instrument/base.py

@@ -17,6 +17,9 @@
     cast,
 )
 
+from functools import wraps
+import inspect
+
 import numpy as np
 
 from qcodes.logger.instrument_logger import get_instrument_logger
@@ -74,6 +77,12 @@ def __init__(self, name: str, metadata: Optional[Mapping[Any, Any]] = None) -> N
 
         self.log = get_instrument_logger(self, __name__)
 
+        if getattr(self, "_call_add_params_from_decorated_methods", True):
+            # setting self._call_add_params_from_decorated_methods=False before calling
+            # `super().__init__()` gives more control in driver whose parameters require
+            # information available only in the `__init__()` of a driver.
+            self._add_params_from_decorated_methods()
+
     @property
     def name(self) -> str:
         """Name of the instrument"""
@@ -401,6 +410,94 @@ def validate_status(self, verbose: bool = False) -> None:
                     print(f'validate_status: param {k}: {value}')
                 p.validate(value)
 
+    def _add_params_from_decorated_methods(self):
+
+        def special_kwargs_to_meth(self, kwarg_value):
+            """
+            Returns the attribute that has the name `kwarg_value.attr_name`
+            of this instance if the kwarg_value is of type `InstanceAttr`.
+            """
+            if isinstance(kwarg_value, InstanceAttr):
+                return getattr(self, kwarg_value.attr_name)
+            return kwarg_value
+
+        # decorated methods are required to have a specific prefix
+        has_parameter_prefix = lambda s: s.startswith(DECORATED_METHOD_PREFIX)
+
+        for obj_name in filter(has_parameter_prefix, dir(self)):
+            meth = getattr(self, obj_name)
+            # the `@add_parameter` decorator adds an attribute we check for here
+            if hasattr(meth, ADD_PARAMETER_ATTR_NAME):
+                kwargs = {
+                    key: special_kwargs_to_meth(self, val.default)
+                    for key, val in sorted(inspect.signature(meth).parameters.items())
+                }
+                self.add_parameter(
+                    name=meth.__name__[len(DECORATED_METHOD_PREFIX):],
+                    docstring=meth.__doc__,
+                    **kwargs,
+                )
+
+
+class InstanceAttr:
+    """
+    An auxiliary class to be used together with the
+    :obj:`qcodes.instrument.base.add_parameter` decorator to allow adding parameters
+    that require information available only during the `__init__()` of an Instrument
+    subclass.
+    """
+    def __init__(self, attr_name: str):
+        """Instantiates the class and saves the passed in attr_name."""
+        self.attr_name: str = attr_name
+
+    def __repr__(self):
+        """Return the class name and `self.attr_name`."""
+        return f"{self.__class__.__name__}('{self.attr_name}')"
+
+
+DECORATED_METHOD_PREFIX = "_parameter_"
+"""
+A constant defining the prefix of the methods on which
+:obj:`qcodes.instrument.base.add_parameter` decorator can be used. The intention is to
+keep the name of these methods fairly unique and private to avoid any foreseeable clash.
+"""
+
+ADD_PARAMETER_ATTR_NAME = "_add_parameter"
+"""
+A constant defining the name of the attribute set by
+:obj:`qcodes.instrument.base.add_parameter` decorator to flag a method that will be
+converted to parameter.
+"""
+
+def add_parameter(method):
+    """
+    A decorator function that wraps a method of an Instrument subclass such that the
+    new method will be converted into the corresponding :code:`param_class`
+    in the :code:`_add_params_from_decorated_methods`.
+
+    Args:
+        method: The method to be wrapped and flagged to be converted to parameter.
+    """
+
+    if DECORATED_METHOD_PREFIX not in method.__name__:
+        raise ValueError(
+            f"Only methods prefixed with '{DECORATED_METHOD_PREFIX}' can be decorated "
+            f"with this decorator."
+        )
+
+    @wraps(method)  # preserves info like `__doc__` and signature
+    def kwargs_and_doc_container(self, *args, **kwargs):
+        raise RuntimeError(
+            f"Method not intended to be called.\n"
+            f"'{method.__name__}' is a special method used as information container "
+            f"for creating and assigning parameters to {self}."
+        )
+
+    # special attribute to flag method for conversion to parameter
+    setattr(kwargs_and_doc_container, ADD_PARAMETER_ATTR_NAME, True)
+
+    return kwargs_and_doc_container
+
 
 class AbstractInstrument(ABC):
     """ABC that is useful for defining mixin classes for Instrument class"""