From cb040dafc15626842a2fb8bade94954dd587df82 Mon Sep 17 00:00:00 2001
From: bakaq <bakaq@bakaq.net>
Date: Sun, 29 Sep 2024 23:30:57 -0300
Subject: [PATCH] Docs for Machine and QueryState

---
 src/machine/lib_machine.rs | 17 +++++++++++------
 src/machine/mod.rs         |  3 +++
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/src/machine/lib_machine.rs b/src/machine/lib_machine.rs
index 4137a985..5f0f4213 100644
--- a/src/machine/lib_machine.rs
+++ b/src/machine/lib_machine.rs
@@ -14,6 +14,7 @@ use super::{
     MachineConfig, PrologTerm,
 };
 
+/// An iterator though the leaf answers of a query.
 pub struct QueryState<'a> {
     machine: &'a mut Machine,
     term: TermWriteResult,
@@ -146,17 +147,20 @@ impl Iterator for QueryState<'_> {
 }
 
 impl Machine {
+    /// Creates a new [`Machine`] configured for use as a library.
     pub fn new_lib() -> Self {
         Machine::new(MachineConfig::default().with_streams(StreamConfig::in_memory()))
     }
 
-    pub fn load_module_string(&mut self, module_name: &str, program: String) {
-        let stream = Stream::from_owned_string(program, &mut self.machine_st.arena);
+    /// Loads a module into the [`Machine`] from a string.
+    pub fn load_module_string(&mut self, module_name: &str, program: impl Into<String>) {
+        let stream = Stream::from_owned_string(program.into(), &mut self.machine_st.arena);
         self.load_file(module_name, stream);
     }
 
-    pub fn consult_module_string(&mut self, module_name: &str, program: String) {
-        let stream = Stream::from_owned_string(program, &mut self.machine_st.arena);
+    /// Consults a module into the [`Machine`] from a string.
+    pub fn consult_module_string(&mut self, module_name: &str, program: impl Into<String>) {
+        let stream = Stream::from_owned_string(program.into(), &mut self.machine_st.arena);
         self.machine_st.registers[1] = stream_as_cell!(stream);
         self.machine_st.registers[2] = atom_as_cell!(&atom_table::AtomTable::build_with(
             &self.machine_st.atom_tbl,
@@ -190,9 +194,10 @@ impl Machine {
         self.machine_st.block = stub_b;
     }
 
-    pub fn run_query(&mut self, query: String) -> QueryState {
+    /// Runs a query.
+    pub fn run_query(&mut self, query: impl Into<String>) -> QueryState {
         let mut parser = Parser::new(
-            Stream::from_owned_string(query, &mut self.machine_st.arena),
+            Stream::from_owned_string(query.into(), &mut self.machine_st.arena),
             &mut self.machine_st,
         );
         let op_dir = CompositeOpDir::new(&self.indices.op_dir, None);
diff --git a/src/machine/mod.rs b/src/machine/mod.rs
index 94f2842f..448734e4 100644
--- a/src/machine/mod.rs
+++ b/src/machine/mod.rs
@@ -70,6 +70,7 @@ lazy_static! {
     pub static ref INTERRUPT: AtomicBool = AtomicBool::new(false);
 }
 
+/// An instance of Scryer Prolog.
 #[derive(Debug)]
 pub struct Machine {
     pub(super) machine_st: MachineState,
@@ -262,6 +263,7 @@ impl Machine {
         )
     }
 
+    /// Gets the current inference count.
     pub fn get_inference_count(&mut self) -> u64 {
         self.machine_st
             .cwil
@@ -480,6 +482,7 @@ impl Machine {
         }
     }
 
+    /// Creates a new [`Machine`] from a [`MachineConfig`].
     #[allow(clippy::new_without_default)]
     pub fn new(config: MachineConfig) -> Self {
         let args = MachineArgs::new();
-- 
2.54.0