docs: add some comments.

Author: rzvxa

tasks/ast_codegen/src/generators/mod.rs

@@ -3,6 +3,14 @@ mod ast_kind;
 mod count_unvisited;
 mod impl_get_span;
 
+/// Inserts a newline in the `TokenStream`.
+#[allow(unused)]
+macro_rules! endl {
+    () => {
+        /* only works in the context of `quote` macro family! */
+    };
+}
+
 /// Similar to how `insert` macro works in the context of `quote` macro family, But this one can be
 /// used outside and accepts expressions.
 /// Wraps the result of the given expression in `insert!({value here});` and outputs it as `TokenStream`.

tasks/ast_codegen/src/linker.rs

@@ -30,12 +30,14 @@ impl<'a> Linker<'a> for CodegenCtx {
         &'a self,
         mut linker: impl FnMut(&mut RType, &'a Self) -> Result<bool>,
     ) -> Result<&'a ()> {
+        // we sort by `TypeId` so we always have the same ordering as how it is written in the rust.
         let mut unresolved = self
             .ident_table
             .iter()
             .sorted_by_key(|it| it.1)
             .map(|it| it.0)
             .collect::<VecDeque<_>>();
+
         while let Some(next) = unresolved.pop_back() {
             let next_id = *self.type_id(next).unwrap();
 
@@ -51,8 +53,7 @@ impl<'a> Linker<'a> for CodegenCtx {
     }
 }
 
-/// Returns false if can't resolve
-/// TODO: right now we don't resolve nested inherits, return is always true for now.
+/// Returns false if can't resolve at the moment
 /// # Panics
 /// On invalid inheritance.
 #[allow(clippy::unnecessary_wraps)]

tasks/ast_codegen/src/schema.rs

@@ -220,12 +220,13 @@ impl Module {
             })
             .map(TryInto::try_into)
             .map_ok(|it| Rc::new(RefCell::new(it)))
-            // .collect::<Vec<RType>>();
             .collect::<Result<_>>()?;
         self.loaded = true;
         Ok(self)
     }
 
+    /// Expand `inherit_variants` macros to their inner enum.
+    /// This would also populate `inherits` field of `EnumMeta` types.
     pub fn expand(self) -> Result<Self> {
         if !self.loaded {
             return Err(String::from(LOAD_ERROR));
@@ -235,6 +236,7 @@ impl Module {
         Ok(self)
     }
 
+    /// Fills the Meta types.
     pub fn analyze(self) -> Result<Self> {
         if !self.loaded {
             return Err(String::from(LOAD_ERROR));
@@ -250,6 +252,7 @@ impl Module {
         }
 
         let definitions = Definitions {
+            // We filter map to get rid of stuff we don't need in our schema.
             types: self.items.into_iter().filter_map(|it| (&*it.borrow()).into()).collect(),
         };
         Ok(Schema { source: self.path, definitions })
@@ -262,6 +265,11 @@ pub fn expand(type_def: &TypeRef) -> Result<()> {
             let (enum_, inherits) = mac
                 .mac
                 .parse_body_with(|input: &ParseBuffer| {
+                    // Because of `@inherit`s we can't use the actual `ItemEnum` parse,
+                    // This closure is similar to how `ItemEnum` parser works, With the exception
+                    // of how we approach our variants, First we try to parse a variant out of our
+                    // tokens if we fail we try parsing the inheritance, And we would raise an
+                    // error only if both of these fail.
                     let attrs = input.call(Attribute::parse_outer)?;
                     let vis = input.parse::<Visibility>()?;
                     let enum_token = input.parse::<Token![enum]>()?;