Add minimal documentation to in ir in trustfall_core

trustfall_core/src/ir/mod.rs

@@ -1,3 +1,4 @@
+//! Trustfall internal representation (IR)
 #![allow(dead_code)]
 
 pub mod indexed;
@@ -26,17 +27,21 @@ lazy_static! {
     pub(crate) static ref TYPENAME_META_FIELD_ARC: Arc<str> = Arc::from(TYPENAME_META_FIELD);
 }
 
+/// Vertex ID
+#[doc(alias("vertex", "node"))]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
-pub struct Vid(pub(crate) NonZeroUsize); // vertex ID
+pub struct Vid(pub(crate) NonZeroUsize);
 
 impl Vid {
     pub fn new(id: NonZeroUsize) -> Vid {
         Vid(id)
     }
 }
 
+/// Edge ID
+#[doc(alias = "edge")]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
-pub struct Eid(pub(crate) NonZeroUsize); // edge ID
+pub struct Eid(pub(crate) NonZeroUsize);
 
 impl Eid {
     pub fn new(id: NonZeroUsize) -> Eid {
@@ -49,8 +54,12 @@ pub struct EdgeParameters(
     #[serde(default, skip_serializing_if = "BTreeMap::is_empty")] pub BTreeMap<Arc<str>, FieldValue>,
 );
 
+/// IR of components of a query, containing information about the vertex ID
+/// of the root of the query, as well as well as maps of all vertices, edges,
+/// folds, and outputs of the query.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct IRQueryComponent {
+    /// The [Vid] of the root, or entry point, of the query.
     pub root: Vid,
 
     #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
@@ -66,6 +75,7 @@ pub struct IRQueryComponent {
     pub outputs: BTreeMap<Arc<str>, ContextField>,
 }
 
+/// Intermediate representation of a query
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct IRQuery {
     pub root_name: Arc<str>,
@@ -94,6 +104,9 @@ pub struct IREdge {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub parameters: Option<Arc<EdgeParameters>>,
 
+    /// Indicating if this edge is optional.
+    ///
+    /// This would correspond to `@optional` in GraphQL.
     #[serde(default = "default_optional", skip_serializing_if = "is_false")]
     pub optional: bool,
 
@@ -123,9 +136,13 @@ impl Recursive {
     }
 }
 
+/// Representation of a vertex (node) in the Trustfall intermediate
+/// representation (IR).
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct IRVertex {
     pub vid: Vid,
+
+    /// The name of the type of the vertex as a string.
     pub type_name: Arc<str>,
 
     #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -282,6 +299,15 @@ impl Argument {
     }
 }
 
+/// Operations that can be made in the graph.
+///
+/// In GraphQL, this can correspond to the `op` argument in `@filter`,
+/// for example in the following:
+/// ```graphql
+/// query Student {
+///     name @filter(op: "has_substring", values: ["John"])
+/// }
+/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum Operation<LeftT, RightT>
@@ -365,6 +391,10 @@ where
         }
     }
 
+    /// The operation name as a `str`
+    ///
+    /// Note that these are the same as would be given to a GraphQL `op`
+    /// argumetn.
     pub(crate) fn operation_name(&self) -> &'static str {
         match self {
             Operation::IsNull(..) => "is_null",

trustfall_core/src/ir/value.rs

@@ -1,7 +1,11 @@
+/// IR of the values of GraphQL fields.
 use async_graphql_value::{ConstValue, Number, Value};
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 
+/// Values of fields in GraphQL types.
+///
+/// For version that is serialized as an untagged enum, see [TransparentValue].
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum FieldValue {
     // Order may matter here! Deserialization, if ever configured for untagged serialization,
@@ -10,17 +14,21 @@ pub enum FieldValue {
     // This is because we want to prioritize the standard Integer GraphQL type over our custom u64,
     // and prioritize exact integers over lossy floats.
     Null,
-    Int64(i64), // AKA Integer
+    /// AKA integer
+    Int64(i64),
     Uint64(u64),
-    Float64(f64), // AKA Float, and also not allowed to be NaN
+    /// AKA Float, and also not allowed to be NaN
+    Float64(f64),
     String(String),
     Boolean(bool),
     DateTimeUtc(DateTime<Utc>),
     Enum(String),
     List(Vec<FieldValue>),
 }
 
-/// Same as FieldValue, but serialized as an untagged enum,
+/// Values of fields in GraphQL types.
+///
+/// Same as [FieldValue], but serialized as an untagged enum,
 /// which may be more suitable e.g. when serializing to JSON.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(untagged)]
@@ -190,6 +198,7 @@ impl From<bool> for FieldValue {
     }
 }
 
+/// Represents a finite (non-infinite, not-NaN) [f64] value
 pub struct FiniteF64(f64);
 impl From<FiniteF64> for FieldValue {
     fn from(f: FiniteF64) -> FieldValue {
@@ -320,6 +329,7 @@ impl<T: Clone + Into<FieldValue>> From<&[T]> for FieldValue {
     }
 }
 
+/// Converts a JSON number to a [FieldValue]
 fn convert_number_to_field_value(n: &Number) -> Result<FieldValue, String> {
     // The order here matters!
     // Int64 must be before Uint64, which must be before Float64.