--Docs cleanup (#2238)

* --add gh tag * --fix ref in doc strings * --fix more refs in docstrings
facebookresearch · Oct 24, 2023 · 7cee5da · 7cee5da
1 parent dfb388e
commit 7cee5da
Show file tree

Hide file tree

Showing 40 changed files with 846 additions and 287 deletions.
diff --git a/docs/namespaces.dox b/docs/namespaces.dox
@@ -8,6 +8,22 @@ namespace esp {
  * @brief Root namespace
  */
 
+/** @namespace esp::agent
+ * @brief Agent library
+ */
+
+/** @namespace esp::assets
+ * @brief Assets library
+ */
+
+/** @namespace esp::core
+ * @brief Core Habitat functionality
+ */
+
+/** @namespace esp::core::config
+ * @brief Configuration functionality
+ */
+
 /** @namespace esp::gfx
  * @brief GFX library
  */
@@ -20,4 +36,24 @@ namespace esp {
  * @brief logging library
  */
 
+/** @namespace esp::metadata
+ * @brief Metadata management
+ */
+
+/** @namespace esp::metadata::attributes
+ * @brief Metadata Attributes library
+ */
+
+/** @namespace esp::metadata::managers
+ * @brief Metadata Attribute Managers library
+ */
+
+/** @namespace esp::metadata::URDF
+ * @brief URDF parsing library
+ */
+
+/** @namespace esp::physics
+ * @brief Physics library
+ */
+
 }
diff --git a/docs/pages/attributesJSON.rst b/docs/pages/attributesJSON.rst
@@ -41,7 +41,7 @@ A *SceneDataset* enumerates and aggregates the various assets and metadata neces
 
      <datasetname>.scene_dataset_config.json
 
-`An example of an appropriately configured SceneDataset Attributes file can be found below <facebookresearch/habitat-sim/blob/main/data/test_assets/dataset_tests/dataset_0/test_dataset_0.scene_dataset_config.json>`_:
+:gh:`An example of an appropriately configured SceneDataset Attributes file can be found below <facebookresearch/habitat-sim/blob/main/data/test_assets/dataset_tests/dataset_0/test_dataset_0.scene_dataset_config.json>`:
 
 .. include:: ../../data/test_assets/dataset_tests/dataset_0/test_dataset_0.scene_dataset_config.json
     :code: json
@@ -256,7 +256,7 @@ A *stage* in Habitat-Sim is the set of STATIC mesh components which make up the
 
      <stagename>.stage_config.json
 
-`An example of an appropriately configured Stage Attributes file can be found below <facebookresearch/habitat-sim/blob/main/data/test_assets/scenes/stage_floor1.stage_config.json>`_:
+:gh:`An example of an appropriately configured Stage Attributes file can be found below <facebookresearch/habitat-sim/blob/main/data/test_assets/scenes/stage_floor1.stage_config.json>`:
 
 .. include:: ../../data/test_assets/scenes/stage_floor1.stage_config.json
     :code: json
@@ -343,7 +343,7 @@ Below are stage-specific physical and object-related quantities.  These values w
 
      <articulated_object_name>.ao_config.json
 
-`An example of an appropriately configured Articulated Object Attributes file can be found below <facebookresearch/habitat-sim/blob/main/data/test_assets/urdf/skinned_prism.ao_config.json>`_:
+:gh:`An example of an appropriately configured Articulated Object Attributes file can be found below <facebookresearch/habitat-sim/blob/main/data/test_assets/urdf/skinned_prism.ao_config.json>`:
 
 .. include:: ../../data/test_assets/urdf/skinned_prism.ao_config.json
     :code: json
@@ -400,7 +400,7 @@ Articulated Object Configuration And Rendering
 
      <objectname>.object_config.json
 
-`An example of an appropriately configured object Attributes file can be found below <facebookresearch/habitat-sim/blob/main/data/test_assets/objects/donut.object_config.json>`_:
+:gh:`An example of an appropriately configured Object Attributes file can be found below <facebookresearch/habitat-sim/blob/main/data/test_assets/objects/donut.object_config.json>`:
 
 .. include:: ../../data/test_assets/objects/donut.object_config.json
     :code: json
@@ -490,7 +490,7 @@ Below are object-specific physical quantities.  These values will override simil
 
      <lightingname>.lighting_config.json
 
-`An example of an appropriately configured LightLayoutAttributes file can be found below <facebookresearch/habitat-sim/blob/main/data/test_assets/lights/test_lights.lighting_config.json>`_:
+:gh:`An example of an appropriately configured LightLayoutAttributes file can be found below <facebookresearch/habitat-sim/blob/main/data/test_assets/lights/test_lights.lighting_config.json>`:
 
 .. include:: ../../data/test_assets/lights/test_lights.lighting_config.json
     :code: json
@@ -524,7 +524,7 @@ The :ref:`LightLayoutAttributes` JSON should contain a single cell named "lights
 
      <pbrIblConfigurationName>.pbr_config.json
 
-`An example of an appropriately configured PBRShader Attributes file can be found below <facebookresearch/habitat-sim/blob/main/data/test_assets/pbr/example.pbr_config.json>`_:
+:gh:`An example of an appropriately configured PBRShader Attributes file can be found below <facebookresearch/habitat-sim/blob/main/data/test_assets/pbr/example.pbr_config.json>`:
 
 .. include:: ../../data/test_assets/pbr/example.pbr_config.json
     :code: json
@@ -629,7 +629,7 @@ These parameters control the enabling or disabling of particular extension layer
 
      <worldname>.physics_config.json
 
-`An example of an appropriately configured Physics Manager Attributes file can be found below <facebookresearch/habitat-sim/blob/main/data/test_assets/testing.physics_config.json>`_:
+:gh:`An example of an appropriately configured Physics Manager Attributes file can be found below <facebookresearch/habitat-sim/blob/main/data/test_assets/testing.physics_config.json>`:
 
 .. include:: ../../data/test_assets/testing.physics_config.json
     :code: json

diff --git a/src/esp/agent/Agent.h b/src/esp/agent/Agent.h
@@ -24,42 +24,87 @@ class SensorSuite;
 }  // namespace sensor
 namespace agent {
 
-// Represents the physical state of an agent
+/**
+ * @brief Struct describing the physical state of an agent
+ */
 struct AgentState {
+  /**
+   * @brief the position of the agent
+   */
   vec3f position = {0, 0, 0};
-  // TODO: rotation below exposes quaternion x,y,z,w as vec4f for pybind11
-  // interop, replace with quatf when we have custom pybind11 type conversion
-  // for quaternions
+  /**
+   * @brief the agent's rotation. TODO : This exposes the rotation quaternion
+   * x,y,z,w as vec4f for pybind11 interop, replace with quatf when we have
+   * custom pybind11 type conversion for quaternions
+   */
   vec4f rotation = {0, 0, 0, 1};
   ESP_SMART_POINTERS(AgentState)
 };
 
+/**
+ * @brief Type to describe the characteristics of an action (i.e. angle to turn
+ * for a turn action)
+ */
 typedef std::map<std::string, float> ActuationMap;
 
-// Specifies an action (i.e. name -> agent actuation).
+/**
+ * @brief Struct describing an action (i.e. name -> agent actuation).
+ */
 struct ActionSpec {
+  /**
+   * @brief Constructor
+   */
   explicit ActionSpec(const std::string& _name, const ActuationMap& _actuation)
       : name(_name), actuation(_actuation) {}
-  // action name
+  /**
+   * @brief action name
+   */
   std::string name;
-  // linear, angular forces, joint torques, sensor actuation
+  /**
+   * @brief linear, angular forces, joint torques, sensor actuation
+   */
   ActuationMap actuation;
   ESP_SMART_POINTERS(ActionSpec)
 };
+
+/**
+ * @brief Verify @ref ActionSpec equality.
+ */
 bool operator==(const ActionSpec& a, const ActionSpec& b);
+
+/**
+ * @brief Verify @ref ActionSpec inequality.
+ */
 bool operator!=(const ActionSpec& a, const ActionSpec& b);
 
-// Represents a set of possible agent actions.
+/**
+ * @brief Represents a set of possible agent actions.
+ */
 typedef std::map<std::string, ActionSpec::ptr> ActionSpace;
 
-// Represents a configuration for an embodied Agent
+/**
+ * @brief Struct describing a configuration for an embodied Agent
+ */
 struct AgentConfiguration {
+  /**
+   * @brief The agent's height
+   */
   float height = 1.5;
+
+  /**
+   * @brief The radius of the colliding capsule around the agent
+   */
   float radius = 0.1;
 
+  /**
+   * @brief A vector of @ref esp::sensor::SensorSpec that describe the sensors attached to this agent.
+   */
   std::vector<std::shared_ptr<sensor::SensorSpec>> sensorSpecifications = {};
 
-  ActionSpace actionSpace = {  // default ActionSpace
+  /**
+   * @brief The default ActionSpace for this agent
+   */
+  ActionSpace actionSpace = {
       {"moveForward",
        ActionSpec::create("moveForward", ActuationMap{{"amount", 0.25f}})},
       {"lookUp", ActionSpec::create("lookUp", ActuationMap{{"amount", 10.0f}})},
@@ -69,52 +114,111 @@ struct AgentConfiguration {
        ActionSpec::create("turnLeft", ActuationMap{{"amount", 10.0f}})},
       {"turnRight",
        ActionSpec::create("turnRight", ActuationMap{{"amount", 10.0f}})}};
+  /**
+   * @brief The body type of this agent.
+   */
   std::string bodyType = "cylinder";
 
   ESP_SMART_POINTERS(AgentConfiguration)
 };
+
+/**
+ *  @brief Verify @ref AgentConfiguration equality.
+ */
 bool operator==(const AgentConfiguration& a, const AgentConfiguration& b);
+
+/**
+ * @brief Verify @ref AgentConfiguration inequality.
+ */
 bool operator!=(const AgentConfiguration& a, const AgentConfiguration& b);
 
-// Represents an agent that can act within an environment
+/**
+ * @brief Class that represents an agent that can act within an environment
+ */
 class Agent : public Magnum::SceneGraph::AbstractFeature3D {
  public:
-  // constructor: the status of the agent, sensors is "valid" after
-  // construction; user can use them immediately
+  /**
+   * @brief constructor: the status of the agent, sensors is "valid" after
+   * construction; user can use them immediately
+   */
   explicit Agent(scene::SceneNode& agentNode, const AgentConfiguration& cfg);
 
   ~Agent() override;
 
-  // Get the scene node being attached to.
+  /**
+   * @brief Get the scene node being attached to.
+   */
   scene::SceneNode& node() { return object(); }
+
+  /**
+   * @brief Get the scene node being attached to.
+   */
   const scene::SceneNode& node() const { return object(); }
 
-  // Overloads to avoid confusion
+  /**
+   * @brief Overloads to avoid confusion
+   */
   scene::SceneNode& object() {
     return static_cast<scene::SceneNode&>(
         Magnum::SceneGraph::AbstractFeature3D::object());
   }
+
+  /**
+   * @brief Overloads to avoid confusion
+   */
   const scene::SceneNode& object() const {
     return static_cast<const scene::SceneNode&>(
         Magnum::SceneGraph::AbstractFeature3D::object());
   }
 
+  /**
+   * @brief Perform an action.
+   * @param actionName the name of the action to perform
+   * @return Whether the named action is available to the agent
+   */
   bool act(const std::string& actionName);
 
+  /**
+   * @brief Verify whether the named action is available to the agent.
+   * @param actionName the name of the action to perform
+   * @return Whether the named action is available to the agent
+   */
   bool hasAction(const std::string& actionName) const;
 
+  /**
+   * @brief Return the agent to the saved @p initialState_
+   */
   void reset();
 
+  /**
+   * @brief Populate the passed state with the agent's current positon and
+   * rotation.
+   * @param state The @ref AgentState variable to populate with the current state of this agent.
+   */
   void getState(const AgentState::ptr& state) const;
 
+  /**
+   * @brief Set the agent to the passsed state.
+   * @param state The state to set the agent to
+   * @param resetSensors Whether to reset the agent's sensors or not.
+   */
   void setState(const AgentState& state, bool resetSensors = true);
 
+  /**
+   * @brief Set the agent to the passsed state and set that state to be the @p
+   * initialState_
+   * @param state The state to set to, and save as initial state
+   * @param resetSensors Whether to reset the agent's sensors or not.
+   */
   void setInitialState(const AgentState& state,
                        const bool resetSensors = true) {
     initialState_ = state;
     setState(state, resetSensors);
   }
 
+  /**
+   * @brief Retrieve the @ref esp::scene::ObjectControls specified for this agent.
+   */
   std::shared_ptr<scene::ObjectControls> getControls() { return controls_; }
 
   /**
@@ -136,17 +240,31 @@ class Agent : public Magnum::SceneGraph::AbstractFeature3D {
     return node().getSubtreeSensors();
   }
 
+  /**
+   * @brief Retrieve a const reference to this agent's configuration.
+   */
   const AgentConfiguration& getConfig() const { return configuration_; }
+
+  /**
+   * @brief Retrieve a reference to this agent's configuration.
+   */
   AgentConfiguration& getConfig() { return configuration_; }
 
-  // Set of actions that are applied to the body of the agent.  These actions
-  // update both the absolute position/rotation of the agent and the sensor
-  // Non-body actions only effect the absolute position and rotation of the
-  // sensors (only effects their position/rotation relative to the agent's body)
+  /**
+   * @brief Set of actions that are applied to the body of the agent.  These
+   * actions update both the absolute position/rotation of the agent and the
+   * sensor. Non-body actions only effect the absolute position and rotation of
+   * the sensors (only effects their position/rotation relative to the agent's
+   * body)
+   */
   static const std::set<std::string> BodyActions;
 
  private:
+  /**
+   * @brief The configuration of this agent.
+   */
   AgentConfiguration configuration_;
+
   std::shared_ptr<scene::ObjectControls> controls_;
   AgentState initialState_;