feat: allow to put comments on the schema file itself

It's now possible to attach a global comment to the root of the schema
by placing a comment on the very top. The comment block needs to be
separated by a newline to split between schema and definition comments.

crates/stef-doc/src/lib.rs

@@ -38,7 +38,10 @@ pub struct Output<'a> {
 pub fn render_schema<'a>(
     _opts: &'a Opts,
     Schema {
-        path, definitions, ..
+        path,
+        comment,
+        definitions,
+        ..
     }: &'a Schema<'_>,
 ) -> Result<Output<'a>> {
     let name = path
@@ -52,6 +55,7 @@ pub fn render_schema<'a>(
         content: templates::Index {
             name,
             path: &path,
+            comment,
             definitions,
         }
         .render()?,

crates/stef-doc/src/templates.rs

@@ -12,6 +12,7 @@ use stef_parser::{Comment, Const, Definition, Enum, Fields, Module, Struct, Type
 pub struct Index<'a> {
     pub name: &'a str,
     pub path: &'a [Rc<str>],
+    pub comment: &'a Comment<'a>,
     pub definitions: &'a [Definition<'a>],
 }
 

crates/stef-doc/templates/index.html

@@ -5,6 +5,9 @@
 {% block content %}
 <div class="section">
   <h2>Schema {{ name }}</h2>
+  <div class="markdown pl-6">
+    {{ self::merge_comments(comment)|markdown|trim|safe }}
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@alias_basic.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/alias_basic.stef
     <main>
 <div class="section">
   <h2>Schema alias_basic</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@attribute_multi.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/attribute_multi.stef
     <main>
 <div class="section">
   <h2>Schema attribute_multi</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@attribute_single.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/attribute_single.stef
     <main>
 <div class="section">
   <h2>Schema attribute_single</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@attribute_unit.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/attribute_unit.stef
     <main>
 <div class="section">
   <h2>Schema attribute_unit</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@attributes.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/attributes.stef
     <main>
 <div class="section">
   <h2>Schema attributes</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@attributes_min_ws.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/attributes_min_ws.stef
     <main>
 <div class="section">
   <h2>Schema attributes_min_ws</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@const_basic.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/const_basic.stef
     <main>
 <div class="section">
   <h2>Schema const_basic</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@const_string.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/const_string.stef
     <main>
 <div class="section">
   <h2>Schema const_string</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@enum_basic.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/enum_basic.stef
     <main>
 <div class="section">
   <h2>Schema enum_basic</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@enum_generics.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/enum_generics.stef
     <main>
 <div class="section">
   <h2>Schema enum_generics</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@enum_many_ws.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/enum_many_ws.stef
     <main>
 <div class="section">
   <h2>Schema enum_many_ws</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@enum_min_ws.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/enum_min_ws.stef
     <main>
 <div class="section">
   <h2>Schema enum_min_ws</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@import_basic.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/import_basic.stef
     <main>
 <div class="section">
   <h2>Schema import_basic</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@mixed.stef.snap

@@ -1,6 +1,6 @@
 ---
 source: crates/stef-doc/tests/render.rs
-description: "/// Basic user information.\n///\n/// Uses various other `structs` and `enums` to compose the information\n/// in a **type safe** way.\nstruct User {\n    name: FullName @1,\n    /// Physical address, might not be specified by the user.\n    address: option<Address> @2,\n    age: u8 @3,\n    birthday: birthday::DayOfBirth @4,\n}\n\n/// Full name of a user.\nstruct FullName {\n    first: string @1,\n    middle: option<string> @2,\n    last: string @3,\n}\n\n/// Simple alias for convenience.\n///\n/// - Might be easier to remember.\n/// - Often referenced as this.\ntype Name = FullName;\n\nstruct Address {\n    /// Street name.\n    street: string @1,\n    /// Number of the house in the street.\n    house_no: HouseNumber @2,\n    city: string @3,\n}\n\n/// The number on the house.\n///\n/// More details can be found at [Wikipedia](https://en.wikipedia.org/wiki/House_numbering).\nenum HouseNumber {\n    /// Digit only number.\n    Digit(u16 @1) @1,\n    /// Mixed _number_ with characters like `1a`.\n    Text(string @1) @2,\n}\n\n/// Probably the max age of a human, currently.\nconst MAX_AGE: u8 = 120;\n\n\n/// Details for defining birthdays.\nmod birthday {\n    /// As the name suggests, specifies details about birthdays.\n    enum DayOfBirth {\n        Specific {\n            year: u16 @1,\n            month: Month @2,\n            day: u8 @3,\n        } @1,\n        /// The user didn't want to say.\n        Secret {\n            /// Optional info from the user about why they didn't want to\n            /// reveal their birthday.\n            reason: option<string> @1,\n        } @2,\n        /// We never asked and nobody knows.\n        Unknown @3,\n    }\n\n    /// Let's assume we only have details of people born **after** this year.\n    const MIN_YEAR: u16 = 1900;\n\n    /// Absolute maximum for a day, but might be even less depending\n    /// on the month.\n    const MAX_DAY: u8 = 31;\n\n    /// The month of the year.\n    enum Month {\n        January @1,\n        February @2,\n        March @3,\n        April @4,\n        May @5,\n        June @6,\n        July @7,\n        August @8,\n        September @9,\n        October @10,\n        November @11,\n        December @12,\n    }\n}"
+description: "/// Schema with a bit of everything, to try out more complex scenarios.\n\n/// Basic user information.\n///\n/// Uses various other `structs` and `enums` to compose the information\n/// in a **type safe** way.\nstruct User {\n    name: FullName @1,\n    /// Physical address, might not be specified by the user.\n    address: option<Address> @2,\n    age: u8 @3,\n    birthday: birthday::DayOfBirth @4,\n}\n\n/// Full name of a user.\nstruct FullName {\n    first: string @1,\n    middle: option<string> @2,\n    last: string @3,\n}\n\n/// Simple alias for convenience.\n///\n/// - Might be easier to remember.\n/// - Often referenced as this.\ntype Name = FullName;\n\nstruct Address {\n    /// Street name.\n    street: string @1,\n    /// Number of the house in the street.\n    house_no: HouseNumber @2,\n    city: string @3,\n}\n\n/// The number on the house.\n///\n/// More details can be found at [Wikipedia](https://en.wikipedia.org/wiki/House_numbering).\nenum HouseNumber {\n    /// Digit only number.\n    Digit(u16 @1) @1,\n    /// Mixed _number_ with characters like `1a`.\n    Text(string @1) @2,\n}\n\n/// Probably the max age of a human, currently.\nconst MAX_AGE: u8 = 120;\n\n\n/// Details for defining birthdays.\nmod birthday {\n    /// As the name suggests, specifies details about birthdays.\n    enum DayOfBirth {\n        Specific {\n            year: u16 @1,\n            month: Month @2,\n            day: u8 @3,\n        } @1,\n        /// The user didn't want to say.\n        Secret {\n            /// Optional info from the user about why they didn't want to\n            /// reveal their birthday.\n            reason: option<string> @1,\n        } @2,\n        /// We never asked and nobody knows.\n        Unknown @3,\n    }\n\n    /// Let's assume we only have details of people born **after** this year.\n    const MIN_YEAR: u16 = 1900;\n\n    /// Absolute maximum for a day, but might be even less depending\n    /// on the month.\n    const MAX_DAY: u8 = 31;\n\n    /// The month of the year.\n    enum Month {\n        January @1,\n        February @2,\n        March @3,\n        April @4,\n        May @5,\n        June @6,\n        July @7,\n        August @8,\n        September @9,\n        October @10,\n        November @11,\n        December @12,\n    }\n}"
 input_file: crates/stef-parser/tests/inputs/mixed.stef
 ---
 --- mixed/index.html
@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/mixed.stef
     <main>
 <div class="section">
   <h2>Schema mixed</h2>
+  <div class="markdown pl-6">
+    <p>Schema with a bit of everything, to try out more complex scenarios.</p>
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@module_basic.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/module_basic.stef
     <main>
 <div class="section">
   <h2>Schema module_basic</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@schema_basic.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/schema_basic.stef
     <main>
 <div class="section">
   <h2>Schema schema_basic</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@struct_basic.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/struct_basic.stef
     <main>
 <div class="section">
   <h2>Schema struct_basic</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@struct_generics.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/struct_generics.stef
     <main>
 <div class="section">
   <h2>Schema struct_generics</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@struct_many_ws.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/struct_many_ws.stef
     <main>
 <div class="section">
   <h2>Schema struct_many_ws</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@struct_min_ws.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/struct_min_ws.stef
     <main>
 <div class="section">
   <h2>Schema struct_min_ws</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@struct_tuple.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/struct_tuple.stef
     <main>
 <div class="section">
   <h2>Schema struct_tuple</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@types_basic.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/types_basic.stef
     <main>
 <div class="section">
   <h2>Schema types_basic</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@types_generic.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/types_generic.stef
     <main>
 <div class="section">
   <h2>Schema types_generic</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@types_nested.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/types_nested.stef
     <main>
 <div class="section">
   <h2>Schema types_nested</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@types_non_zero.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/types_non_zero.stef
     <main>
 <div class="section">
   <h2>Schema types_non_zero</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-doc/tests/snapshots/render__render@types_ref.stef.snap

@@ -22,6 +22,9 @@ input_file: crates/stef-parser/tests/inputs/types_ref.stef
     <main>
 <div class="section">
   <h2>Schema types_ref</h2>
+  <div class="markdown pl-6">
+
+  </div>
 </div>
 <div class="section">
   <h3>Modules</h3>

crates/stef-lsp/src/handlers/compile.rs

@@ -32,6 +32,7 @@ fn parse_schema_diagnostic(index: &LineIndex, e: &ParseSchemaError) -> Diagnosti
         ParseSchemaCause::Parser(_, at) => {
             Diagnostic::new_simple(get_range(index, *at..*at), e.to_string())
         }
+        ParseSchemaCause::Comment(e) => parse_comment_diagnostic(index, e),
         ParseSchemaCause::Definition(e) => parse_definition_diagnostic(index, e),
     }
 }

crates/stef-parser/src/error.rs

@@ -80,13 +80,16 @@ impl Diagnostic for ParseSchemaError {
 pub enum ParseSchemaCause {
     Parser(ErrorKind, usize),
     #[diagnostic(transparent)]
+    Comment(ParseCommentError),
+    #[diagnostic(transparent)]
     Definition(ParseDefinitionError),
 }
 
 impl Error for ParseSchemaCause {
     fn source(&self) -> Option<&(dyn Error + 'static)> {
         match self {
             Self::Parser(kind, _) => kind.source(),
+            Self::Comment(inner) => inner.source(),
             Self::Definition(inner) => inner.source(),
         }
     }
@@ -96,11 +99,18 @@ impl Display for ParseSchemaCause {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
             Self::Parser(kind, _) => kind.fmt(f),
+            Self::Comment(inner) => inner.fmt(f),
             Self::Definition(inner) => inner.fmt(f),
         }
     }
 }
 
+impl From<ParseCommentError> for ParseSchemaCause {
+    fn from(value: ParseCommentError) -> Self {
+        Self::Comment(value)
+    }
+}
+
 impl From<ParseDefinitionError> for ParseSchemaCause {
     fn from(value: ParseDefinitionError) -> Self {
         Self::Definition(value)

crates/stef-parser/src/lib.rs

@@ -112,6 +112,8 @@ pub struct Schema<'a> {
     pub path: Option<PathBuf>,
     /// Original source code form which this schema was parsed.
     pub source: &'a str,
+    /// Optional schema-level comment.
+    pub comment: Comment<'a>,
     /// List of all the definitions that make up the schema.
     pub definitions: Vec<Definition<'a>>,
 }
@@ -146,6 +148,10 @@ impl<'a> Schema<'a> {
 
 impl Display for Schema<'_> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        if !self.comment.0.is_empty() {
+            writeln!(f, "{}", self.comment)?;
+        }
+
         for definition in &self.definitions {
             writeln!(f, "{definition}")?;
         }