Adds tests and docs.

Signed-off-by: Franco Cipollone <[email protected]>

maliput/src/api/rules/mod.rs

@@ -481,11 +481,17 @@ impl UniqueBulbGroupId {
     }
 }
 
+/// Interface for querying "rules of the road". This interface
+/// provides access to static information about a road network (i.e.,
+/// information determined prior to the beginning of a simulation). Some
+/// rule types may refer to additional dynamic information which will be
+/// provided by other interfaces.
 pub struct RoadRulebook<'a> {
     pub(super) road_rulebook: &'a maliput_sys::api::rules::ffi::RoadRulebook,
 }
 
 impl<'a> RoadRulebook<'a> {
+    /// Returns the DiscreteValueRule with the specified `id`.
     pub fn get_discrete_value_rule(&self, rule_id: &String) -> DiscreteValueRule {
         DiscreteValueRule {
             discrete_value_rule: maliput_sys::api::rules::ffi::RoadRulebook_GetDiscreteValueRule(
@@ -496,12 +502,35 @@ impl<'a> RoadRulebook<'a> {
     }
 }
 
+/// ## Rule
+///
+/// A Rule may have multiple states that affect agent behavior while it is
+/// driving through the rule's zone. The possible states of a Rule must be
+/// semantically coherent. The current state of a Rule is given by a
+/// [RuleStateProvider]. States can be:
+///
+/// - range based ([RangeValueRule]).
+/// - discrete ([DiscreteValueRule]).
+///
+/// ## DiscreteValueRule
+///
+/// [DiscreteValue]s are defined by a string value.
+/// Semantics of this rule are based on _all_ possible values that this
+/// [DiscreteValueRule::type_id] could have (as specified by RuleRegistry::FindRuleByType()),
+/// not only the subset of values that a specific instance of this rule can
+/// be in.
 pub struct DiscreteValueRule {
     discrete_value_rule: cxx::UniquePtr<maliput_sys::api::rules::ffi::DiscreteValueRule>,
 }
 
 impl DiscreteValueRule {
+    /// Returns the Id of the rule as a string.
     pub fn id(&self) -> String {
         maliput_sys::api::rules::ffi::DiscreteValueRule_id(&self.discrete_value_rule)
     }
+    /// Returns the type of the rule as a string.
+    /// Example: "right-of-way-rule-type-id", "direction-usage-rule-type-id"
+    pub fn type_id(&self) -> String {
+        maliput_sys::api::rules::ffi::DiscreteValueRule_type_id(&self.discrete_value_rule)
+    }
 }

maliput/tests/common/mod.rs

@@ -67,6 +67,47 @@ pub fn create_t_shape_road_network_with_books() -> RoadNetwork {
     RoadNetwork::new("maliput_malidrive", &road_network_properties)
 }
 
+#[allow(dead_code)]
+pub fn create_loop_road_pedestrian_crosswalk_road_network_with_books() -> RoadNetwork {
+    let rm = ResourceManager::new();
+    let loop_road_pedestrian_crosswalk_xodr_path = rm
+        .get_resource_path_by_name("maliput_malidrive", "LoopRoadPedestrianCrosswalk.xodr")
+        .unwrap();
+    let loop_road_pedestrian_crosswalk_books_path = rm
+        .get_resource_path_by_name("maliput_malidrive", "LoopRoadPedestrianCrosswalk.yaml")
+        .unwrap();
+
+    let road_network_properties = HashMap::from([
+        ("road_geometry_id", "my_rg_from_rust"),
+        (
+            "opendrive_file",
+            loop_road_pedestrian_crosswalk_xodr_path.to_str().unwrap(),
+        ),
+        (
+            "road_rule_book",
+            loop_road_pedestrian_crosswalk_books_path.to_str().unwrap(),
+        ),
+        (
+            "rule_registry",
+            loop_road_pedestrian_crosswalk_books_path.to_str().unwrap(),
+        ),
+        (
+            "traffic_light_book",
+            loop_road_pedestrian_crosswalk_books_path.to_str().unwrap(),
+        ),
+        (
+            "phase_ring_book",
+            loop_road_pedestrian_crosswalk_books_path.to_str().unwrap(),
+        ),
+        (
+            "intersection_book",
+            loop_road_pedestrian_crosswalk_books_path.to_str().unwrap(),
+        ),
+        ("linear_tolerance", "0.01"),
+    ]);
+    RoadNetwork::new("maliput_malidrive", &road_network_properties)
+}
+
 #[allow(dead_code)]
 pub fn assert_inertial_position_equality(
     left: &maliput::api::InertialPosition,

maliput/tests/road_rulebook_test.rs

@@ -0,0 +1,46 @@
+// BSD 3-Clause License
+//
+// Copyright (c) 2024, Woven by Toyota.
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met:
+//
+// * Redistributions of source code must retain the above copyright notice, this
+//   list of conditions and the following disclaimer.
+//
+// * Redistributions in binary form must reproduce the above copyright notice,
+//   this list of conditions and the following disclaimer in the documentation
+//   and/or other materials provided with the distribution.
+//
+// * Neither the name of the copyright holder nor the names of its
+//   contributors may be used to endorse or promote products derived from
+//   this software without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+// OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+mod common;
+
+// TShapeRoad maps is being used to test the road rulebook API and its components.
+// YAML information about the RoadRulebook can be found at:
+// https://github.com/maliput/maliput_malidrive/blob/352601969b1363cc13fe2008c198a3d95843bf5b/resources/LoopRoadPedestrianCrosswalk.yaml#L64
+
+#[test]
+fn road_rulebook_test_api() {
+    let road_network = common::create_loop_road_pedestrian_crosswalk_road_network_with_books();
+
+    let book = road_network.rulebook();
+    let expected_rule_id = String::from("Vehicle-Stop-In-Zone-Behavior Rule Type/WestToEastSouth");
+    let expected_type_id = String::from("Vehicle-Stop-In-Zone-Behavior Rule Type");
+    let rule = book.get_discrete_value_rule(&expected_rule_id);
+    assert_eq!(rule.id(), expected_rule_id);
+    assert_eq!(rule.type_id(), expected_type_id);
+}