More docstrings in schema-ast

libs/datamodel/parser-database/src/attributes.rs

@@ -4,7 +4,7 @@ mod map;
 mod native_types;
 
 use crate::{
-    ast,
+    ast::{self, WithName, WithSpan},
     context::{Arguments, Context},
     types::{
         EnumAttributes, FieldWithArgs, IndexAlgorithm, IndexAttribute, IndexType, ModelAttributes, RelationField,
@@ -358,7 +358,7 @@ fn visit_model_ignore(model_id: ast::ModelId, model_data: &mut ModelAttributes<'
             DatamodelError::new_attribute_validation_error(
                 "Fields on an already ignored Model do not need an `@ignore` annotation.",
                 "ignore",
-                ctx.db.ast[model_id][field_id].span,
+                *ctx.db.ast[model_id][field_id].span(),
             )
         })
         .collect();

libs/datamodel/parser-database/src/attributes/id.rs

@@ -1,6 +1,6 @@
 use super::FieldResolutionError;
 use crate::{
-    ast::{self, WithSpan},
+    ast::{self, WithName, WithSpan},
     attributes::resolve_field_array_with_args,
     context::{Arguments, Context},
     types::{FieldWithArgs, IdAttribute, ModelAttributes, SortOrder},

libs/datamodel/parser-database/src/attributes/map.rs

@@ -1,5 +1,5 @@
 use crate::{
-    ast,
+    ast::{self, WithName},
     context::{Arguments, Context},
     types::{CompositeTypeField, ModelAttributes, ScalarField},
     DatamodelError,

libs/datamodel/parser-database/src/types.rs

@@ -1,5 +1,5 @@
 use crate::{context::Context, walkers::CompositeTypeFieldWalker, walkers::CompositeTypeWalker, DatamodelError};
-use schema_ast::ast;
+use schema_ast::ast::{self, WithName};
 use std::{
     collections::{BTreeMap, HashMap},
     fmt,

libs/datamodel/parser-database/src/walkers/model.rs

@@ -9,8 +9,9 @@ use super::{
     ScalarFieldWalker,
 };
 use crate::{
-    ast,
-    {types::ModelAttributes, ParserDatabase},
+    ast::{self, WithName},
+    types::ModelAttributes,
+    ParserDatabase,
 };
 use std::hash::{Hash, Hasher};
 

libs/datamodel/schema-ast/src/ast.rs

@@ -62,17 +62,20 @@ impl SchemaAst {
         })
     }
 
+    /// Iterate over all the top-level items in the schema.
     pub fn iter_tops(&self) -> impl Iterator<Item = (TopId, &Top)> {
         self.tops
             .iter()
             .enumerate()
             .map(|(top_idx, top)| (top_idx_to_top_id(top_idx, top), top))
     }
 
+    /// Iterate over all the datasource blocks in the schema.
     pub fn sources(&self) -> impl Iterator<Item = &SourceConfig> {
         self.tops.iter().filter_map(|top| top.as_source())
     }
 
+    /// Iterate over all the generator blocks in the schema.
     pub fn generators(&self) -> impl Iterator<Item = &GeneratorConfig> {
         self.tops.iter().filter_map(|top| top.as_generator())
     }
@@ -135,11 +138,17 @@ pub struct SourceId(u32);
 /// syntax to resolve the id to an `ast::Top`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum TopId {
+    /// A composite type
     CompositeType(CompositeTypeId),
+    /// A model declaration
     Model(ModelId),
+    /// An enum declaration
     Enum(EnumId),
+    /// A type alias
     Alias(AliasId),
+    /// A generator block
     Generator(GeneratorId),
+    /// A datasource block
     Source(SourceId),
 }
 
@@ -152,13 +161,15 @@ impl TopId {
         }
     }
 
+    /// Try to interpret the top as a model.
     pub fn as_model_id(self) -> Option<ModelId> {
         match self {
             TopId::Model(model_id) => Some(model_id),
             _ => None,
         }
     }
 
+    /// Try to interpret the top as a composite type.
     pub fn as_composite_type_id(&self) -> Option<CompositeTypeId> {
         match self {
             TopId::CompositeType(ctid) => Some(*ctid),

libs/datamodel/schema-ast/src/ast/find_at_position.rs

@@ -1,6 +1,7 @@
 use crate::ast::{self, top_idx_to_top_id, traits::*};
 
 impl ast::SchemaAst {
+    /// Find the AST node at the given position (byte offset).
     pub fn find_at_position(&self, position: usize) -> SchemaPosition<'_> {
         self.find_top_at_position(position)
             .map(|top_id| match top_id {

libs/datamodel/schema-ast/src/ast/identifier.rs

@@ -1,12 +1,16 @@
 use super::{Span, WithSpan};
 
+/// An identifier.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Identifier {
+    /// The identifier contents.
     pub name: String,
+    /// The span of the AST node.
     pub span: Span,
 }
 
 impl Identifier {
+    /// Instantiate a new identifier with an empty span.
     pub fn new(name: &str) -> Identifier {
         Identifier {
             name: String::from(name),

libs/datamodel/schema-ast/src/ast/model.rs

@@ -52,10 +52,6 @@ impl Model {
     pub fn find_field_bang(&self, name: &str) -> &Field {
         self.find_field(name).unwrap()
     }
-
-    pub fn name(&self) -> &str {
-        &self.name.name
-    }
 }
 
 impl WithIdentifier for Model {

libs/datamodel/schema-ast/src/ast/top.rs

@@ -5,15 +5,22 @@ use crate::ast::{
 /// Enum for distinguishing between top-level entries
 #[derive(Debug, Clone, PartialEq)]
 pub enum Top {
+    /// A composite type
     CompositeType(CompositeType),
+    /// An enum declaration
     Enum(Enum),
+    /// A model declaration
     Model(Model),
+    /// A datasource block
     Source(SourceConfig),
+    /// A generator block
     Generator(GeneratorConfig),
+    /// A type alias
     Type(Field),
 }
 
 impl Top {
+    /// A string saying what kind of item this is.
     pub fn get_type(&self) -> &str {
         match self {
             Top::CompositeType(_) => "composite type",
@@ -25,6 +32,7 @@ impl Top {
         }
     }
 
+    /// The name of the item.
     pub fn identifier(&self) -> &Identifier {
         match self {
             Top::CompositeType(ct) => &ct.name,
@@ -36,45 +44,52 @@ impl Top {
         }
     }
 
+    /// The name of the item.
     pub fn name(&self) -> &str {
         &self.identifier().name
     }
 
+    /// Try to interpret the item as a composite type declaration.
     pub fn as_composite_type(&self) -> Option<&CompositeType> {
         match self {
             Top::CompositeType(ct) => Some(ct),
             _ => None,
         }
     }
 
+    /// Try to interpret the item as a model declaration.
     pub fn as_model(&self) -> Option<&Model> {
         match self {
             Top::Model(model) => Some(model),
             _ => None,
         }
     }
 
+    /// Try to interpret the item as an enum declaration.
     pub fn as_enum(&self) -> Option<&Enum> {
         match self {
             Top::Enum(r#enum) => Some(r#enum),
             _ => None,
         }
     }
 
+    /// Try to interpret the item as a generator block.
     pub fn as_generator(&self) -> Option<&GeneratorConfig> {
         match self {
             Top::Generator(gen) => Some(gen),
             _ => None,
         }
     }
 
+    /// Try to interpret the item as a type alias.
     pub fn as_type_alias(&self) -> Option<&Field> {
         match self {
             Top::Type(r#type) => Some(r#type),
             _ => None,
         }
     }
 
+    /// Try to interpret the item as a datasource block.
     pub fn as_source(&self) -> Option<&SourceConfig> {
         match self {
             Top::Source(source) => Some(source),

libs/datamodel/schema-ast/src/ast/traits.rs

@@ -1,24 +1,35 @@
 use super::{Attribute, Comment, Identifier, Span};
 
+/// An AST node with a span.
 pub trait WithSpan {
+    /// The span of the node.
     fn span(&self) -> &Span;
 }
 
+/// An AST node with a name (from the identifier).
 pub trait WithName {
+    /// The name of the item.
     fn name(&self) -> &str;
 }
 
+/// An AST node with an identifier.
 pub trait WithIdentifier {
+    /// The identifier.
     fn identifier(&self) -> &Identifier;
 }
 
+/// An AST node with attributes.
 pub trait WithAttributes {
+    /// The attributes.
     fn attributes(&self) -> &[Attribute];
 }
 
+/// An AST node with documentation.
 pub trait WithDocumentation {
+    /// The documentation string, if defined.
     fn documentation(&self) -> &Option<Comment>;
 
+    /// Is this node commented out?
     fn is_commented_out(&self) -> bool;
 }
 

libs/datamodel/schema-ast/src/parser/datamodel.pest

@@ -124,7 +124,7 @@ BLOCK_LEVEL_CATCH_ALL = { !BLOCK_CLOSE ~ CATCH_ALL }
 function = { non_empty_identifier ~ "(" ~ (expression ~ ("," ~ expression)*)? ~ ")" }
 field_with_args = {  non_empty_identifier ~ "(" ~ argument ~ ("," ~ argument)*  ~")"}
 array_expression = { "[" ~ (expression ~ ( "," ~ expression )*)? ~ "]" }
-expression = { field_with_args | array_expression | function | numeric_literal | string_literal | constant_literal }
+expression = { function | field_with_args | array_expression | numeric_literal | string_literal | constant_literal }
 
 // ######################################
 // Literals / Values