more detailed core docs

src/core.rs

@@ -21,9 +21,13 @@ pub use self::serialization::*;
 pub use self::slice_deserializer::*;
 pub use self::typeless::*;
 
+/// Basic support for tracing events across the execution.
 pub trait Diagnostic<T: Monad> {
+    /// Specify that the evaluation happens after a specific event.
     fn after<'a, A>(fa: T::F<'a, A>, event: &'a str) -> T::F<'a, A>;
+    /// Specify that the evaluation happens before a specific event.
     fn before<'a, A>(fa: T::F<'a, A>, event: &'a str) -> T::F<'a, A>;
+    /// Label the evaluation step as a specific named action.
     fn wrapped<'a, A>(fa: T::F<'a, A>, event: &'a str) -> T::F<'a, A>;
 }
 
@@ -32,8 +36,11 @@ pub trait Context {
     /// Type to provide for [Monad]ic representation of computation, mostly that of resolution ([`Resolution`]).
     type T: Monad;
 
+    /// Type to allow improved support for result evaluation.
+    /// This is important for async applications stopping early.
     type Fallible: MonadFailOver<Self::T>;
 
+    /// See [`Diagnostic`].
     type D: Diagnostic<Self::T>;
 
     /// Type to represent resolution errors mainly arising in [`Resolver::resolve`].
@@ -108,7 +115,11 @@ pub trait Origin<'a, Ctx: 'a + Context>: 'a {
 
 /// The main way to represent a reference in ADN.
 pub struct Point<'a, Ctx: 'a + Context, A: Mentionable<'a, Ctx>> {
+    /// Hash of the referred content.
+    /// Derived both from the serialised value ([`Serializable::serialize`])
+    /// and its topology ([`Mentionable::topology`]).
     pub point: Hash,
+    /// [Origin] used in [`Point::resolve`].
     pub origin: Rc<dyn Origin<'a, Ctx, Mtbl = A>>,
 }
 

src/core/resolution.rs

@@ -3,7 +3,9 @@ use super::*;
 /// Failure yielded by [`Origin`].
 #[derive(Debug)]
 pub enum ResolutionError<L, P> {
+    /// Usually comes from [`Resolver::resolve`].
     Lookup(L),
+    /// Usually comes from [`Factory::deserialize`].
     Parse(P),
 }
 

src/core/serialization.rs

@@ -8,7 +8,7 @@ use super::*;
 pub trait Serializer {
     /// Writes bytes from a slice. Should advance value of [`Serializer::tell()`] by `buf.len()`.
     fn write(&mut self, buf: &[u8]);
-    /// Current position of the stream. It's expected to be used by [`crate::std::inlining`]
+    /// Current position of the stream. Used by [`crate::std::inlining::CheckedSerialize`].
     fn tell(&self) -> usize;
 }
 
@@ -36,7 +36,7 @@ pub trait Deserializer {
     fn read_n(&mut self, n: usize) -> &[u8];
     /// Read til the end of the stream.
     fn read_all(&mut self) -> &[u8];
-    /// See [`Serializer::tell`].
+    /// Current position of the stream. Used by [`crate::std::inlining::CheckedParse`].
     fn tell(&self) -> usize;
 }