Fix bugs and add comments to standard library.

src/packages/map_basic.rs

@@ -20,15 +20,32 @@ def_package! {
 
 #[export_module]
 mod map_functions {
+    /// Return the number of properties in the object map.
     #[rhai_fn(pure)]
     pub fn len(map: &mut Map) -> INT {
         map.len() as INT
     }
+    /// Clear the object map.
     pub fn clear(map: &mut Map) {
         if !map.is_empty() {
             map.clear();
         }
     }
+    /// Remove any property of the specified `name` from the object map, returning its value.
+    ///
+    /// If the property does not exist, `()` is returned.
+    ///
+    /// # Example
+    ///
+    /// ```rhai
+    /// let m = #{a:1, b:2, c:3};
+    ///
+    /// let x = m.remove("b");
+    ///
+    /// print(x);       // prints 2
+    ///
+    /// print(m);       // prints "#{a:1, c:3}"
+    /// ```
     pub fn remove(map: &mut Map, name: ImmutableString) -> Dynamic {
         if !map.is_empty() {
             map.remove(name.as_str()).unwrap_or_else(|| Dynamic::UNIT)
@@ -36,12 +53,38 @@ mod map_functions {
             Dynamic::UNIT
         }
     }
+    /// Add all property values of another object map into the object map.
+    /// Existing property values of the same names are replaced.
+    ///
+    /// # Example
+    ///
+    /// ```rhai
+    /// let m = #{a:1, b:2, c:3};
+    /// let n = #{a: 42, d:0};
+    ///
+    /// m.mixin(n);
+    ///
+    /// print(m);       // prints "#{a:42, b:2, c:3, d:0}"
+    /// ```
     #[rhai_fn(name = "mixin", name = "+=")]
     pub fn mixin(map: &mut Map, map2: Map) {
         if !map2.is_empty() {
             map.extend(map2.into_iter());
         }
     }
+    /// Make a copy of the object map, add all property values of another object map
+    /// (existing property values of the same names are replaced), then returning it.
+    ///
+    /// # Example
+    ///
+    /// ```rhai
+    /// let m = #{a:1, b:2, c:3};
+    /// let n = #{a: 42, d:0};
+    ///
+    /// print(m + n);       // prints "#{a:42, b:2, c:3, d:0}"
+    ///
+    /// print(m);           // prints "#{a:1, b:2, c:3}"
+    /// ```
     #[rhai_fn(name = "+")]
     pub fn merge(map1: Map, map2: Map) -> Map {
         if map2.is_empty() {
@@ -54,6 +97,19 @@ mod map_functions {
             map1
         }
     }
+    /// Add all property values of another object map into the object map.
+    /// Only properties that do not originally exist in the object map are added.
+    ///
+    /// # Example
+    ///
+    /// ```rhai
+    /// let m = #{a:1, b:2, c:3};
+    /// let n = #{a: 42, d:0};
+    ///
+    /// m.fill_with(n);
+    ///
+    /// print(m);       // prints "#{a:1, b:2, c:3, d:0}"
+    /// ```
     pub fn fill_with(map: &mut Map, map2: Map) {
         if !map2.is_empty() {
             if map.is_empty() {
@@ -65,6 +121,22 @@ mod map_functions {
             }
         }
     }
+    /// Return `true` if two object maps are equal (i.e. all property values are equal).
+    ///
+    /// The operator `==` is used to compare property values and must be defined,
+    /// otherwise `false` is assumed.
+    ///
+    /// # Example
+    ///
+    /// ```rhai
+    /// let m1 = #{a:1, b:2, c:3};
+    /// let m2 = #{a:1, b:2, c:3};
+    /// let m3 = #{a:1, c:3};
+    ///
+    /// print(m1 == m2);        // prints true
+    ///
+    /// print(m1 == m3);        // prints false
+    /// ```
     #[rhai_fn(name = "==", return_raw, pure)]
     pub fn equals(ctx: NativeCallContext, map1: &mut Map, map2: Map) -> RhaiResultOf<bool> {
         if map1.len() != map2.len() {
@@ -92,11 +164,36 @@ mod map_functions {
 
         Ok(true)
     }
+    /// Return `true` if two object maps are not equal (i.e. at least one property value is not equal).
+    ///
+    /// The operator `==` is used to compare property values and must be defined,
+    /// otherwise `false` is assumed.
+    ///
+    /// # Example
+    ///
+    /// ```rhai
+    /// let m1 = #{a:1, b:2, c:3};
+    /// let m2 = #{a:1, b:2, c:3};
+    /// let m3 = #{a:1, c:3};
+    ///
+    /// print(m1 != m2);        // prints false
+    ///
+    /// print(m1 != m3);        // prints true
+    /// ```
     #[rhai_fn(name = "!=", return_raw, pure)]
     pub fn not_equals(ctx: NativeCallContext, map1: &mut Map, map2: Map) -> RhaiResultOf<bool> {
         equals(ctx, map1, map2).map(|r| !r)
     }
 
+    /// Return an array with all the property names in the object map.
+    ///
+    /// # Example
+    ///
+    /// ```rhai
+    /// let m = #{a:1, b:2, c:3};
+    ///
+    /// print(m.keys());        // prints ["a", "b", "c"]
+    /// ```
     #[cfg(not(feature = "no_index"))]
     #[rhai_fn(pure)]
     pub fn keys(map: &mut Map) -> Array {
@@ -106,6 +203,15 @@ mod map_functions {
             map.keys().cloned().map(Into::into).collect()
         }
     }
+    /// Return an array with all the property values in the object map.
+    ///
+    /// # Example
+    ///
+    /// ```rhai
+    /// let m = #{a:1, b:2, c:3};
+    ///
+    /// print(m.values());      // prints "[1, 2, 3]""
+    /// ```
     #[cfg(not(feature = "no_index"))]
     #[rhai_fn(pure)]
     pub fn values(map: &mut Map) -> Array {