fix grammar

crates/lsp/src/database.rs

@@ -19,23 +19,19 @@ use syntax::{
 
 /**
 * We will store
-* Open data -> Parse -> output -> Syntax -> analyzer -> db{
-   FileID {
-       Template {
-           signal,
-
-       }
-   }
-
-                               value
-   Template map: { Hash(FileID, token) -> Template}
-   Vars map: {Hash(FileID, template, token)} -> Var}
-   Component map {Hash(FileID, template, token)} -> ComponentInfo
-   Signals map {Hash(FileID, template, token)} -> Signal
-
-
+* Open data -> Parse -> output -> Syntax -> analyzer -> db
+    {
+        FileID {
+            Template {
+                signal,
+            }
+        }
 
-}
+        Template map: { Hash(FileID, token) -> Template}
+        Vars map: {Hash(FileID, template, token)} -> Var}
+        Component map {Hash(FileID, template, token)} -> ComponentInfo
+        Signals map {Hash(FileID, template, token)} -> Signal
+    }
 */
 
 #[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]

crates/parser/src/grammar.rs

@@ -12,38 +12,57 @@ mod pragma;
 mod statement;
 mod template;
 
-/**
- * parse circom program
- */
-
 pub mod entry {
 
-    use crate::token_kind::TokenKind;
-
     use super::*;
 
+    /// Parses a full Circom program from top-level constructs.
+    ///
+    /// This function handles parsing of all valid top-level elements in a Circom file,
+    /// such as pragmas, templates, includes, component instantiations, and function
+    /// definitions. Invalid tokens are flagged with an error.
+    ///
+    /// Grammar:
+    /// * `<CircomProgram>` ::= { `<Pragma>` | `<Include>` | `<Template>` | `<Component>` | `<Function>` }
+    ///
+    /// Example:
+    /// ```ignore
+    /// pragma circom 2.0.0;
+    /// include "utils.circom";
+    ///
+    /// template Adder(a, b) {
+    ///     signal input a;
+    ///     signal input b;
+    ///     signal output c;
+    ///     c <== a + b;
+    /// }
+    ///
+    /// function double(x) -> y {
+    ///     y = x * 2;
+    /// }
+    ///
+    /// component main = Adder(1, 2);
+    /// ```
+    /// * `<Pragma>`: `pragma circom 2.0.0;`
+    /// * `<Include>`: `include "utils.circom";`
+    /// * `<Template>`: A circuit blueprint, e.g. `template Adder(...) { ... }`
+    /// * `<Function>`: A reusable logic function, e.g. `function double(...) -> ... { ... }`
+    /// * `<Component>`: An instance of a template, e.g. `component main = Adder(...);`
+    ///
     pub fn circom_program(p: &mut Parser) {
         let m = p.open();
 
-        while p.at_any(&[
-            TokenKind::BlockComment,
-            TokenKind::CommentLine,
-            TokenKind::EndLine,
-            TokenKind::WhiteSpace,
-        ]) {
-            p.skip();
-        }
-
         while !p.eof() {
             match p.current() {
                 PragmaKw => pragma::pragma(p),
                 TemplateKw => template::template(p),
                 IncludeKw => include::include(p),
                 ComponentKw => main_component::main_component(p),
-                FunctionKw => function::function_parse(p),
+                FunctionKw => function::function(p),
                 _ => p.advance_with_error("invalid token"),
             }
         }
+
         p.close(m, CircomProgram);
     }
 

crates/parser/src/grammar/function.rs

@@ -1,22 +1,56 @@
-use list::tuple_identifier;
-
 use crate::grammar::*;
+use block::block;
+use list::parameter_list;
 
-// fucntion name()
-pub fn function_parse(p: &mut Parser) {
+/// Functions define generic abstract pieces of code that can perform some computations
+/// to obtain a value or an expression to be returned.
+///
+/// Grammar:
+/// * `function <FunctionName> <ParameterList> <FunctionBody>`
+///
+///  Example:
+///  ```ignore
+///  function nbits(a) {
+///     var n = 1;
+///     var r = 0;
+///     while (n-1<a) {
+///         r++;
+///         n *= 2;
+///     }
+///     return r;
+///  }
+/// ```
+/// * `<FunctionName>`: `nbits`
+/// * `<ParameterList>`: `(a)`
+/// * `<FunctionBody>`: `{ var n = 1; ... return r; }`
+///
+pub fn function(p: &mut Parser) {
     let m = p.open();
 
     p.expect(FunctionKw);
 
-    let fn_name_marker = p.open();
-    p.expect(Identifier);
-    p.close(fn_name_marker, FunctionName);
+    function_name(p);
 
-    let parameter_marker = p.open();
-    tuple_identifier(p);
-    p.close(parameter_marker, ParameterList);
+    parameter_list(p);
 
-    block::block(p);
+    let body_marker = p.open();
+    block(p);
+    p.close(body_marker, FunctionBody);
 
     p.close(m, FunctionDef);
 }
+
+/// Function name used to identify a function.
+///
+/// Grammar: `Identifier`
+///
+/// Example:
+/// ```ignore
+/// MyFunction
+/// ```
+/// * `Identifier`: `MyFunction`.
+pub fn function_name(p: &mut Parser) {
+    let m = p.open();
+    p.expect(Identifier);
+    p.close(m, FunctionName);
+}

crates/parser/src/grammar/include.rs

@@ -1,11 +1,19 @@
 use super::*;
 
+/// In order to use code in other files, we have to
+/// include them in our program.
+///
+/// Grammar:
+/// * `include "<filename>";`
+///
+/// Example:
+/// ```ignore
+/// include "circuit.circom";
+/// ```
 pub(super) fn include(p: &mut Parser) {
-    // assert!(p.at(IncludeKw));
-
     let m = p.open();
     p.expect(IncludeKw);
     p.expect(CircomString);
     p.expect(Semicolon);
-    p.close(m, IncludeKw);
+    p.close(m, Include);
 }

crates/parser/src/grammar/list.rs

@@ -1,59 +1,65 @@
 use crate::grammar::{expression::expression, *};
 
-/**
- * grammar: "(expression-1, expression-2,..., expression-n)"
- * can be an empty ()
- */
-pub(super) fn tuple_expression(p: &mut Parser) {
-    // let m = p.open();
-    p.expect(LParen);
+/// Argument list used to pass parameters to a template/function instantiation.
+///
+/// Grammar: `(expression-1, expression-2,..., expression-n)`
+///
+/// Example:
+/// ```ignore
+/// component comp = MyTemplate( 2,3 );
+/// ```
+/// * `expression-1`: `2`
+/// * `expression-2`: `3`
+pub fn argument_list(p: &mut Parser) {
+    let m = p.open();
 
-    // expression-1, expression-2,..., expression-n)
-    while !p.at(RParen) && !p.eof() {
-        expression(p);
+    tuple_expression(p);
 
-        // there are no expressions remaining
-        if !p.eat(Comma) {
-            break;
-        }
-    }
+    p.close(m, ArgumentList);
+}
 
-    p.expect(RParen);
+/// Parameter list used to pass parameters to a template/function definition.
+///
+/// Grammar: `(iden-1, iden-2,..., iden-n)`
+/// Can be an empty `()`.
+///
+/// Example:
+/// ```ignore
+/// template MyTemplate( a, b ) {
+/// ...
+/// }
+/// ```
+/// * `iden-1`: `a`
+/// * `iden-2`: `b`
+pub fn parameter_list(p: &mut Parser) {
+    let m = p.open();
 
-    // p.close(m, ExpressionList);
+    tuple_identifier(p);
+
+    p.close(m, ParameterList);
 }
 
-/**
- * grammar: "(iden1, iden2,..., idenn)"
- * can be an empty ()
- */
-pub(super) fn tuple_identifier(p: &mut Parser) {
-    // let m = p.open();
+/// Grammar: `(expression-1, expression-2,..., expression-n)`
+/// Can be an empty `()`.
+pub(super) fn tuple_expression(p: &mut Parser) {
     p.expect(LParen);
 
-    // iden1, iden2, iden3
-    while p.at(Identifier) && !p.eof() {
-        p.expect(Identifier);
+    while !p.at(RParen) && !p.eof() {
+        expression(p);
 
         if !p.eat(Comma) {
             break;
         }
     }
 
     p.expect(RParen);
-    // p.close(m, IdentifierList);
 }
 
-/**
- * grammar: "[iden1, iden2,..., idenn]"
- * can be an empty ()
- * only use in main component.
- */
-pub(super) fn list_identifier(p: &mut Parser) {
-    // let m = p.open();
-    p.expect(LBracket);
+/// Grammar: `(iden-1, iden-2,..., iden-n)`
+/// Can be an empty `()`.
+pub(super) fn tuple_identifier(p: &mut Parser) {
+    p.expect(LParen);
 
-    // iden1, iden2, iden3
     while p.at(Identifier) && !p.eof() {
         p.expect(Identifier);
 
@@ -62,6 +68,5 @@ pub(super) fn list_identifier(p: &mut Parser) {
         }
     }
 
-    p.expect(RBracket);
-    // p.close(m, IdentifierList);
+    p.expect(RParen);
 }