[DEV-7084] TAMER: AsgBuilder and IR lowering docs

tamer/src/ir/mod.rs

@@ -59,6 +59,17 @@
 //!        a graph data structure,
 //!          and is capable of representing entire programs composed of many
 //!          different packages.
+//!
+//! Lowering
+//! ========
+//! IRs are progressively _lowered_ to other IRs that are closer to the
+//!   final representation emitted by the compiler ("lower"-level).
+//!
+//! - [`xmlo::reader`](crate::obj::xmlo::reader) produces
+//!     [`XmloEvent`](crate::obj::xmlo::XmloEvent)s containing
+//!     [`legacyir`].
+//!   - [`xmlo::asg_builder`](crate::obj::xmlo::asg_builder) immediately lowers
+//!       those into [`asg`].
 
 pub mod asg;
 pub mod legacyir;

tamer/src/obj/xmlo/asg_builder.rs

@@ -17,6 +17,57 @@
 //  You should have received a copy of the GNU General Public License
 //  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+//! Lower [Legacy IR](crate::ir::legacyir) derived from [`XmloEvent`]
+//!   into [`Asg`].
+//!
+//! [`AsgBuilder`] is exclusively responsible for this lowering operation
+//!   within the context of [`xmlo` object files](super).
+//!
+//! Usage
+//! =====
+//! [`AsgBuilder`] accepts any [`Iterator`] of [`XmloEvent`]s,
+//!   but is intended to be paired with [`XmloReader`](super::XmloReader).
+//!
+//! To fully load an `xmlo` file and its dependencies,
+//!   begin with [`AsgBuilder::import_xmlo`] and an empty
+//!   [`AsgBuilderState`].
+//! Each call accepts the previous state and returns a new state that may be
+//!   used both for introspection and for the next call to `import_xmlo`.
+//! [`AsgBuilderState::found`] can be used to recursively load relative
+//!   package paths;
+//!     it is wrapped in an [`Option`] so that [`take`](Option::take) can be
+//!       used to take ownership over the data.
+//!
+//! ```
+//! use tamer::global;
+//! use tamer::ir::asg::{DefaultAsg, IdentObject};
+//! use tamer::obj::xmlo::{AsgBuilder, AsgBuilderState, XmloReader};
+//! use tamer::sym::{DefaultInterner, Interner};
+//! use fxhash::FxBuildHasher;
+//! use std::io::BufReader;
+//!
+//! let src_xmlo: &[u8] = br#"<package>
+//!     <preproc:symtable>
+//!       <preproc:sym name="foo" type="cgen" src="dep/package" />
+//!     </preproc:symtable>
+//!     <preproc:fragments>
+//!     </preproc:fragments>
+//!   </package>"#;
+//!
+//! let interner = DefaultInterner::new();
+//! let xmlo = XmloReader::new(src_xmlo, &interner);
+//! let mut asg = DefaultAsg::<'_, IdentObject, global::ProgIdentSize>::new();
+//!
+//! let state = asg.import_xmlo(xmlo, AsgBuilderState::<'_, FxBuildHasher, _>::new());
+//!
+//! // Use `state.found` to recursively load dependencies.
+//! let AsgBuilderState { found, .. } = state.expect("unexpected failure");
+//! assert_eq!(
+//!     vec![&"dep/package"],
+//!     found.unwrap().iter().collect::<Vec<_>>(),
+//! );
+//! ```
+
 use super::reader::{XmloError, XmloEvent, XmloResult};
 use crate::ir::asg::{
     Asg, AsgError, IdentKind, IdentKindError, IdentObjectState, IndexType,
@@ -109,6 +160,7 @@ where
 ///
 /// For more information on what data are processed,
 ///   see [`AsgBuilderState`].
+/// See the [module-level documentation](self) for example usage.
 pub trait AsgBuilder<'i, O, S, Ix>
 where
     O: IdentObjectState<'i, O>,

tamer/src/obj/xmlo/mod.rs

@@ -73,6 +73,17 @@
 //!   <!-- Expanded src -->
 //! </package>
 //! ```
+//!
+//! IR Lowering
+//! ===========
+//! `xmlo` files are represented by the [Legacy IR](crate::ir::legacyir),
+//!   which is emitted during read by [`AsgBuilder`].
+//! For more information about how they are lowered into the
+//!   [ASG](crate::ir::asg),
+//!     see [`asg_builder`].
+//!
+//! For a summary of IRs and how they interact,
+//!   see [`crate::ir`].
 
 mod asg_builder;
 mod reader;