doc(rengine): add more to ast.rs

Author: W95Psp

rust-printer/src/ast/span.rs

@@ -1,31 +1,40 @@
 //! Source positions.
 
 use hax_rust_engine_macros::*;
-use std::sync::atomic::{AtomicUsize, Ordering};
 
-static CURRENT_ID: AtomicUsize = AtomicUsize::new(0);
-
-fn new_id() -> usize {
+/// Creates a fresh identifier for a span.
+fn fresh_id() -> usize {
+    use std::sync::atomic::{AtomicUsize, Ordering};
+    static CURRENT_ID: AtomicUsize = AtomicUsize::new(0);
     CURRENT_ID.fetch_add(1, Ordering::Relaxed)
 }
 
-/// Id for the origin item of a span
+/// Identifier used to track the origin Rust item of a span
 #[derive_group_for_ast]
 pub struct OwnerId(usize);
 
-/// Position in the source code
+/// Position of a Rust source
 #[derive_group_for_ast]
 pub struct Span {
+    /// A vector of spans as defined by the frontend.
+    /// This is useful for supporting in a trivial way union of spans.
     data: Vec<hax_frontend_exporter::Span>,
+    /// A unique identifier. Since we store spans almost for every node of the
+    /// AST, having a unique identifier for spans gives us a fine-grained way of
+    /// refering to sub-nodes in debugging context. This id is indeed mostly
+    /// used by the web debugger.
     id: usize,
+    /// A reference to the item in which this span lives. This information is
+    /// used for debugging and profiling purposes, e.g. for `cargo hax into
+    /// --stats backend`.
     owner_hint: Option<OwnerId>,
 }
 
 impl From<hax_frontend_exporter::Span> for Span {
     fn from(span: hax_frontend_exporter::Span) -> Self {
         Self {
             data: vec![span],
-            id: new_id(),
+            id: fresh_id(),
             owner_hint: None, // TODO: Have something there when we implement the importer
         }
     }