From d465d06895677b236cf966bb29313217c9d1b7a8 Mon Sep 17 00:00:00 2001
From: timofey <tim@ongoteam.yaconnect.com>
Date: Mon, 24 Apr 2023 23:17:40 +0000
Subject: [PATCH] more detailed core docs

---
 src/core.rs               | 11 +++++++++++
 src/core/resolution.rs    |  2 ++
 src/core/serialization.rs |  4 ++--
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/src/core.rs b/src/core.rs
index 95c3af2..b2472ad 100644
--- a/src/core.rs
+++ b/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>>,
 }
 
diff --git a/src/core/resolution.rs b/src/core/resolution.rs
index 9ec901d..87376be 100644
--- a/src/core/resolution.rs
+++ b/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),
 }
 
diff --git a/src/core/serialization.rs b/src/core/serialization.rs
index aa9c051..050035a 100644
--- a/src/core/serialization.rs
+++ b/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;
 }