Improve docstrings

great_ai/parameters/log_metric.py

@@ -6,6 +6,15 @@ from ..tracing import TracingContext
 
 
 def log_metric(argument_name: str, value: Any) -> None:
+    """Log a key (argument_name)-value pair that is persisted inside the trace.
+
+    The name of the function from where this is called is also stored.
+
+    Args:
+        argument_name: The key for storing the value.
+        value: Value to log. Must be JSON-serialisable.
+    """
+
     tracing_context = TracingContext.get_current_tracing_context()
     caller = inspect.stack()[1].function
     actual_name = f"metric:{caller}:{argument_name}"

great_ai/parameters/parameter.py

@@ -19,6 +19,10 @@ def parameter(
 ) -> Callable[[F], F]:
     """Control the validation and logging of function parameters.
 
+    Basically, a parameter decorator. Unfortunately, Python does not have that concept,
+    thus, it's a method decorator that expects the name of the to-be-decorated
+    parameter.
+
     Examples:
         >>> @parameter('a')
         ... def my_function(a: int):
@@ -39,7 +43,7 @@ def parameter(
         great_ai.errors.argument_validation_error.ArgumentValidationError: ...
 
     Args:
-        parameter_name: Name of parameter to consider
+        parameter_name: Name of parameter to consider.
         validate: Optional validate to run against the concrete argument.
             ArgumentValidationError is thrown when the return value is False.
         disable_logging: Do not save the value in any active TracingContext.