improved docstrings for sql data routines

microsoft · Dec 4, 2024 · aa29bde · aa29bde
1 parent a57b0d7
commit aa29bde
Showing 1 changed file with 18 additions and 7 deletions.
diff --git a/mlos_bench/mlos_bench/storage/sql/common.py b/mlos_bench/mlos_bench/storage/sql/common.py
@@ -23,11 +23,14 @@ def get_trials(
     tunable_config_id: Optional[int] = None,
 ) -> Dict[int, TrialData]:
     """
-    Gets TrialData for the given experiment_data and optionally additionally restricted
-    by tunable_config_id.
+    Gets :py:class:`~.TrialData` for the given ``experiment_id`` and optionally
+    additionally restricted by ``tunable_config_id``.
 
-    Used by both TunableConfigTrialGroupSqlData and ExperimentSqlData.
-    """
+    See Also
+    --------
+    - :py:class:`~mlos_bench.storage.sql.tunable_config_trial_group_data.TunableConfigTrialGroupSqlData`
+    - :py:class:`~mlos_bench.storage.sql.experiment_data.ExperimentSqlData`
+    """  # pylint: disable=line-too-long # noqa: E501
     # pylint: disable=import-outside-toplevel,cyclic-import
     from mlos_bench.storage.sql.trial_data import TrialSqlData
 
@@ -71,11 +74,19 @@ def get_results_df(
     tunable_config_id: Optional[int] = None,
 ) -> pandas.DataFrame:
     """
-    Gets TrialData for the given experiment_data and optionally additionally restricted
+    Gets TrialData for the given experiment_id and optionally additionally restricted
     by tunable_config_id.
 
-    Used by both TunableConfigTrialGroupSqlData and ExperimentSqlData.
-    """
+    The returned DataFrame includes each trial's metadata, config, and results in
+    wide format, with config parameters prefixed with
+    :py:data:`ExperimentData.CONFIG_COLUMN_PREFIX` and results prefixed with
+    :py:data:`ExperimentData.RESULT_COLUMN_PREFIX`.
+
+    See Also
+    --------
+    - :py:class:`~mlos_bench.storage.sql.tunable_config_trial_group_data.TunableConfigTrialGroupSqlData`
+    - :py:class:`~mlos_bench.storage.sql.experiment_data.ExperimentSqlData`
+    """  # pylint: disable=line-too-long # noqa: E501
     # pylint: disable=too-many-locals
     with engine.connect() as conn:
         # Compose a subquery to fetch the tunable_config_trial_group_id for each tunable config.