Merge pull request trueagi-io#737 from vsbogd/fix-rustdocs

Fix documentation rendering warnings

lib/src/atom/matcher.rs

@@ -75,7 +75,7 @@ enum VarResolutionResult<T> {
 }
 
 /// Abstraction of the variable set. It is used to allow passing both
-/// HashSet<&VariableAtom> and HashSet<VariableAtom> to the
+/// `HashSet<&VariableAtom>` and `HashSet<VariableAtom>` to the
 /// [Bindings::narrow_vars] method.
 pub trait VariableSet : Debug {
     type Iter<'a> : Iterator<Item = &'a VariableAtom> where Self: 'a;
@@ -829,7 +829,7 @@ impl Debug for Bindings {
 impl PartialEq for Bindings {
 
     /// This implementation is for testing only. It doesn't take into account
-    /// names of the renamed variables (see [Binding::var]).
+    /// names of the renamed variables (see `Binding::var`).
     fn eq(&self, other: &Self) -> bool {
         for (var, self_binding_id) in &self.binding_by_var {
             match other.binding_by_var.get(var) {
@@ -1001,7 +1001,7 @@ impl BindingsSet {
     ///
     /// NOTE: This function is useful for making a Bindings Iterator that returns no results,
     /// as you might want for a return from a GroundedAtom match function that matched no atoms.
-    /// In other cases, you probably want to use [BinsingsSet::single].
+    /// In other cases, you probably want to use [Self::single].
     pub fn empty() -> Self {
         BindingsSet(smallvec::smallvec![])
     }
@@ -1014,15 +1014,15 @@ impl BindingsSet {
     /// Returns `true` if a BindingsSet contains no Bindings Objects (fully constrained)
     ///
     /// TODO: Need a better name that doesn't conflict with the intuitions about Bindings::is_empty()
-    /// https://github.com/trueagi-io/hyperon-experimental/issues/281
+    /// [issue#281](https://github.com/trueagi-io/hyperon-experimental/issues/281)
     pub fn is_empty(&self) -> bool {
         self.len() == 0
     }
 
     /// Returns `true` if a BindingsSet contains no limiting Bindings inside (unconstrained)
     ///
     /// TODO: Need a better word to describe this concept than "single"
-    /// https://github.com/trueagi-io/hyperon-experimental/issues/281
+    /// [issue#281](https://github.com/trueagi-io/hyperon-experimental/issues/281)
     pub fn is_single(&self) -> bool {
         self.len() == 1 && self.0[0].is_empty()
     }

lib/src/atom/mod.rs

@@ -238,7 +238,7 @@ impl VariableAtom {
         name
     }
 
-    /// Constructs new variable instance by parsing name in format '<name>[#<id>]'.
+    /// Constructs new variable instance by parsing name in format `<name>[#<id>]`.
     /// Used to construct variable from result of the [VariableAtom::name] results.
     ///
     /// # Examples

lib/src/metta/runner/environment.rs

@@ -14,7 +14,7 @@ use directories::ProjectDirs;
 /// Contains state and host platform interfaces shared by all MeTTa runners.  This includes config settings
 /// and logger
 ///
-/// Generally there will be only one environment object needed, and it can be accessed by calling the [common_env] method
+/// Generally there will be only one environment object needed, and it can be accessed by calling the [Self::common_env] method
 #[derive(Debug)]
 pub struct Environment {
     config_dir: Option<PathBuf>,
@@ -131,7 +131,7 @@ impl EnvBuilder {
     /// NOTE: Unless otherwise specified, the default working directory will be the current process
     /// working dir (`cwd`)
     ///
-    /// NOTE: Unless otherwise specified by calling either [set_no_config_dir] or [set_config_dir], the
+    /// NOTE: Unless otherwise specified by calling either [Self::set_no_config_dir] or [Self::set_config_dir], the
     ///   [Environment] will be configured using files in the OS-Specific configuration file locations.
     ///
     /// Depending on the host OS, the config directory locations will be:
@@ -239,21 +239,21 @@ impl EnvBuilder {
         self
     }
 
-    /// Initializes the shared common Environment, accessible with [common_env]
+    /// Initializes the shared common Environment, accessible with [Environment::common_env]
     ///
     /// NOTE: This method will panic if the common Environment has already been initialized
     pub fn init_common_env(self) {
         self.try_init_common_env().expect("Fatal Error: Common Environment already initialized");
     }
 
-    /// Initializes the shared common Environment.  Non-panicking version of [init_common_env]
+    /// Initializes the shared common Environment.  Non-panicking version of [Self::init_common_env]
     pub fn try_init_common_env(self) -> Result<(), &'static str> {
         COMMON_ENV.set(Arc::new(self.build())).map_err(|_| "Common Environment already initialized")
     }
 
     /// Returns a newly created Environment from the builder configuration
     ///
-    /// NOTE: Creating owned Environments is usually not necessary.  It is usually sufficient to use the [common_env] method.
+    /// NOTE: Creating owned Environments is usually not necessary.  It is usually sufficient to use the [Environment::common_env] method.
     pub(crate) fn build(self) -> Environment {
         let mut env = self.env;
         #[cfg(feature = "pkg_mgmt")]

lib/src/metta/runner/modules/mod.rs

@@ -221,7 +221,7 @@ impl MettaMod {
         Ok(())
     }
 
-    /// Returns `true` if a module used [import_all_from_dependency] to import a specific loaded dependency
+    /// Returns `true` if the `self` module has imported the `mod_id` module as a sub-dependency
     pub fn contains_imported_dep(&self, mod_id: &ModId) -> bool {
         let deps_table = self.imported_deps.lock().unwrap();
         deps_table.contains_key(&mod_id)

lib/src/metta/runner/pkg_mgmt/catalog.rs

@@ -506,7 +506,7 @@ pub trait FsModuleFormat: std::fmt::Debug + Send + Sync {
     /// Returns the possible paths inside a parent directory which may point to a module
     ///
     /// NOTE: This function is allowed to return paths that may not be valid.  Paths returned
-    /// from this method will be passed to [try_path] to validate them.
+    /// from this method will be passed to [Self::try_path] to validate them.
     fn paths_for_name(&self, parent_dir: &Path, mod_name: &str) -> Vec<PathBuf>;
 
     /// Checks a specific path, and returns a [ModuleLoader] and a [ModuleDescriptor] if a

lib/src/space/mod.rs

@@ -207,10 +207,10 @@ pub trait Space: std::fmt::Debug + std::fmt::Display {
         None
     }
 
-    /// Returns an &dyn [Any] for spaces where this is possible
+    /// Returns an `&dyn `[Any](std::any::Any) for spaces where this is possible
     fn as_any(&self) -> Option<&dyn std::any::Any>;
 
-    /// Returns an &mut dyn [Any] for spaces where this is possible
+    /// Returns an `&mut dyn `[Any](std::any::Any) for spaces where this is possible
     fn as_any_mut(&mut self) -> Option<&mut dyn std::any::Any>;
 }
 
@@ -274,7 +274,7 @@ pub trait SpaceMut: Space {
     fn replace(&mut self, from: &Atom, to: Atom) -> bool;
 
     /// Turn a &dyn SpaceMut into an &dyn Space.  Obsolete when Trait Upcasting is stabilized.
-    /// https://github.com/rust-lang/rust/issues/65991  Any month now.
+    /// [Rust issue #65991](https://github.com/rust-lang/rust/issues/65991)  Any month now.
     fn as_space(&self) -> &dyn Space;
 }