From 873c4033eb39b52351aeac8f707ade8a608c6d1a Mon Sep 17 00:00:00 2001
From: Kenshin Abe <abe.kenshin@gmail.com>
Date: Wed, 26 Apr 2023 15:43:41 +0900
Subject: [PATCH] Add docstring for register_*_form_widgets

---
 docs/api.rst                     |  1 +
 optuna_dashboard/_form_widget.py | 80 ++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)

diff --git a/docs/api.rst b/docs/api.rst
index 53b59d24..061e93fc 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -23,6 +23,7 @@ Human-in-the-loop
    :nosignatures:
 
    optuna_dashboard.register_objective_form_widgets
+   optuna_dashboard.register_user_attr_form_widgets
    optuna_dashboard.dict_to_form_widget
    optuna_dashboard.ChoiceWidget
    optuna_dashboard.SliderWidget
diff --git a/optuna_dashboard/_form_widget.py b/optuna_dashboard/_form_widget.py
index d9a80b69..622295e7 100644
--- a/optuna_dashboard/_form_widget.py
+++ b/optuna_dashboard/_form_widget.py
@@ -291,6 +291,45 @@ def dict_to_form_widget(d: dict[str, Any]) -> ObjectiveFormWidget:
 def register_objective_form_widgets(
     study: optuna.Study, widgets: list[ObjectiveFormWidget]
 ) -> None:
+    """
+    Register a list of form widgets to an Optuna study.
+
+    Submitted values to the forms are told as each trial's objective values.
+
+    Args:
+        study: The Optuna study object to register the form widgets for.
+        widgets: A list of ObjectiveFormWidget objects to be registered in the study.
+
+    Raises:
+        ValueError: If the length of study directions is not equal to the length of widgets.
+        Warning: If any widget has `user_attr_key` specified, but it will not be used.
+
+    Examples:
+        .. code-block:: python
+
+            import optuna
+            from optuna_dashboard import ChoiceWidget, SliderWidget
+            from optuna_dashboard import register_objective_form_widgets
+
+
+            study = optuna.create_study()
+            register_objective_form_widgets(
+                study,
+                widgets=[
+                    ObjectiveChoiceWidget(
+                        choices=["Good 👍", "Bad 👎"],
+                        values=[-1, 1],
+                        description="Please input your score!",
+                    ),
+                    ObjectiveSliderWidget(
+                        min=1,
+                        max=10,
+                        step=1,
+                        description="Higher is better.",
+                    ),
+                ],
+            )
+    """
     if len(study.directions) != len(widgets):
         raise ValueError("The length of actions must be the same with the number of objectives.")
     if any(
@@ -307,6 +346,47 @@ def register_objective_form_widgets(
 def register_user_attr_form_widgets(
     study: optuna.Study, widgets: list[ObjectiveFormWidget]
 ) -> None:
+    """
+    Register a list of form widgets to an Optuna study.
+
+    Submitted values to the forms are registered as each trial's user_attrs.
+
+    Args:
+        study: The Optuna study object to register the form widgets for.
+        widgets: A list of ObjectiveFormWidget objects to be registered in the study.
+
+    Raises:
+        ValueError: If an ObjectiveUserAttrRef is specified or if `user_attr_key` is not specified.
+        ValueError: If `user_attr_key` is not unique for each widget.
+
+    Examples:
+        .. code-block:: python
+
+            import optuna
+            from optuna_dashboard import ChoiceWidget, SliderWidget
+            from optuna_dashboard import register_user_attr_form_widgets
+
+
+            study = optuna.create_study()
+            register_user_attr_form_widgets(
+                study,
+                widgets=[
+                    ChoiceWidget(
+                        choices=["Good 👍", "Bad 👎"],
+                        values=[-1, 1],
+                        description="Please input your score!",
+                        user_attr_key="hitl/choice",
+                    ),
+                    SliderWidget(
+                        min=1,
+                        max=10,
+                        step=1,
+                        description="Higher is better.",
+                        user_attr_key="hitl/slider",
+                    ),
+                ],
+            )
+    """
     user_attr_keys = set()
     widget_dicts: list[Union[ChoiceWidgetJSON, SliderWidgetJSON, TextInputWidgetJSON]] = []
     for w in widgets: