[BE] - Update docstrings and formatting for sims.habitat_simulator.object_state_machine.py

habitat-lab/habitat/sims/habitat_simulator/object_state_machine.py

@@ -4,6 +4,8 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
+"""This module implements a singleton state-machine architecture for representing and managing non-geometric object states via metadata manipulation. For example, tracking and manipulating state such as "powered on" or "clean vs dirty". This interface is intended to provide a foundation which can be extended for downstream applications."""
+
 from collections import defaultdict
 from typing import Any, Dict, List, Union
 
@@ -15,7 +17,10 @@
 from habitat.sims.habitat_simulator.debug_visualizer import (
     draw_object_highlight,
 )
-from habitat_sim.physics import ManagedArticulatedObject, ManagedRigidObject
+from habitat_sim.physics import (  # BUG: IMPORT ISSUE.  HTML DOCUMENTATION WILL NOT RENDER
+    ManagedArticulatedObject,
+    ManagedRigidObject,
+)
 
 ##################################################
 # Supporting utilities for getting and setting metadata values in ManagedObject "user_defined" Configurations.
@@ -31,7 +36,6 @@ def get_state_of_obj(
 
     :param obj: The ManagedObject.
     :param state_name: The name/key of the object state property to query.
-
     :return: The state value (variable type) or None if not found.
     """
 
@@ -90,7 +94,6 @@ def is_affordance_of_obj(
         Determine whether or not an object instance can have this ObjectStateSpec by checking semantic class against the configured set.
 
         :param obj: The ManagedObject instance.
-
         :return: Whether or not the object has this state affordance.
         """
 
@@ -127,6 +130,7 @@ def update_state(
 
     def default_value(self) -> Any:
         """
+        BUG: IS THIS FUNCTION SAFE??
         If an object does not have a value for this state defined, return a default value.
         """
 
@@ -170,6 +174,7 @@ def __init__(self):
 
     def default_value(self) -> Any:
         """
+        BUG: IS THIS FUNCTION SAFE??
         If an object does not have a value for this state defined, return a default value.
         """
 
@@ -206,7 +211,6 @@ def toggle(
         Toggles a boolean state, returning the newly set value.
 
         :param obj: The ManagedObject instance.
-
         :return: The new value of the state.
         """
 
@@ -312,21 +316,22 @@ def get_snapshot_dict(
         """
         Scrape all active ObjectStateSpecs to collect a snapshot of the current state of all objects.
 
+        :param sim: The Simulator instance for which to collect and return current object states.
         :return: The state snapshot as a Dict keyed by object state unique name, value is another dict mapping object instance handles to state values.
 
         Example:
-        {
-            "is_powered_on": {
-                "my_lamp.0001": True,
-                "my_oven": False,
-                ...
-            },
-            "is_clean": {
-                "my_dish.0002:" False,
-                ...
-            },
-            ...
-        }
+        >>> {
+        >>>     "is_powered_on": {
+        >>>         "my_lamp.0001": True,
+        >>>         "my_oven": False,
+        >>>         ...
+        >>>     },
+        >>>     "is_clean": {
+        >>>         "my_dish.0002:" False,
+        >>>         ...
+        >>>     },
+        >>>     ...
+        >>> }
         """
         snapshot: Dict[str, Dict[str, Any]] = defaultdict(lambda: {})
         for object_handle, states in self.objects_with_states.items():