Add minimal frontend docs

trustfall_core/src/frontend/mod.rs

@@ -1,3 +1,4 @@
+//! Frontend for Trustfall: takes a parsed query, validates it, and turns it into IR.
 #![allow(dead_code, unused_variables, unused_mut)]
 use std::{
     collections::BTreeMap, convert::TryFrom, iter::successors, num::NonZeroUsize, sync::Arc,
@@ -41,6 +42,9 @@ mod tags;
 mod util;
 mod validation;
 
+/// Parses a query string to the Trustfall IR using a provided
+/// [Schema](crate::schema::Schema). May fail if [parse_to_ir](parse_to_ir)
+/// fails for the provided schema and query.
 pub fn parse(schema: &Schema, query: impl AsRef<str>) -> Result<Arc<IndexedQuery>, FrontendError> {
     let ir_query = parse_to_ir(schema, query)?;
 
@@ -53,6 +57,7 @@ pub fn parse(schema: &Schema, query: impl AsRef<str>) -> Result<Arc<IndexedQuery
     Ok(Arc::from(indexed_query))
 }
 
+/// Parses a query string to IR using a [Schema](crate::schema::Schema)
 pub fn parse_to_ir<T: AsRef<str>>(schema: &Schema, query: T) -> Result<IRQuery, FrontendError> {
     let document = async_graphql_parser::parse_query(query)?;
     let q = parse_document(&document)?;

trustfall_core/src/frontend/util.rs

@@ -5,6 +5,8 @@ use async_graphql_value::Name;
 
 use crate::ir::Vid;
 
+/// Retrieves the underlying type name by looping through any [list
+/// types](BaseType::List) until a [named type](Type) is found
 pub(super) fn get_underlying_named_type(t: &Type) -> &Name {
     let mut base_type = &t.base;
     loop {
@@ -36,6 +38,9 @@ impl ComponentPath {
         self.path.push(component_start_vid);
     }
 
+    /// Pops the last component of the current path.
+    ///
+    /// Will panic if the popped value is not the provided `component_start_vid`
     pub(super) fn pop(&mut self, component_start_vid: Vid) {
         let popped_vid = self.path.pop().unwrap();
         assert_eq!(popped_vid, component_start_vid);