Improve parser (#1237)

* chore: rename test to tests
* docs: add docs and comments to doccomment
* reduce allocations in doccomment
* add doccomment tests
* docs: add comments and docs to diagnostics
* reduce allocations in parse
* use ThisError for LexicalError, change result type
* docs: document everything
* feat: add helpers mod, impl CodeLocation for PT
* fix: don't use ref
* feat: implement Display for all PT structs
* feat: implement Display for all PT enums
* feat: add Ord implementations
* feat: implement CodeLocation for smart pointers
* feat: add more helpers
* feat: finish pt::Expression impl
* fix: make helpers module public
* fix: use enum discriminant for sorting

Signed-off-by: DaniPopes <[email protected]>

Author: DaniPopes

solang-parser/Cargo.toml

@@ -19,6 +19,8 @@ lalrpop-util = "0.19"
 phf = { version = "0.11", features = ["macros"] }
 unicode-xid = "0.2"
 itertools = "0.10"
+thiserror = "1.0"
+
 serde = { version = "1.0", features = ["derive"], optional = true }
 
 [dev-dependencies]

solang-parser/src/diagnostics.rs

@@ -1,18 +1,33 @@
 // SPDX-License-Identifier: Apache-2.0
 
+//! Solidity parser diagnostics.
+
 use crate::pt;
 use crate::pt::Loc;
+use std::fmt;
 
+/// The level of a diagnostic.
 #[derive(Clone, Debug, Hash, PartialOrd, Ord, PartialEq, Eq)]
 pub enum Level {
+    /// Debug diagnostic level.
     Debug,
+    /// Info diagnostic level.
     Info,
+    /// Warning diagnostic level.
     Warning,
+    /// Error diagnostic level.
     Error,
 }
 
+impl fmt::Display for Level {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
 impl Level {
-    pub fn to_string(&self) -> &'static str {
+    /// Returns this type as a static string slice.
+    pub fn as_str(&self) -> &'static str {
         match self {
             Level::Debug => "debug",
             Level::Info => "info",
@@ -22,33 +37,51 @@ impl Level {
     }
 }
 
-#[derive(Clone, Debug, Hash, PartialOrd, Ord, PartialEq, Eq)]
+/// The type of a diagnostic.
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum ErrorType {
+    /// No specific error type.
     None,
+    /// Parser error.
     ParserError,
+    /// Syntax error.
     SyntaxError,
+    /// Declaration error.
     DeclarationError,
+    /// Cast error.
     CastError,
+    /// Type error.
     TypeError,
+    /// Warning.
     Warning,
 }
 
-#[derive(Clone, Debug, Hash, PartialOrd, Ord, PartialEq, Eq)]
+/// A diagnostic note.
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct Note {
+    /// The code location of the note.
     pub loc: pt::Loc,
+    /// The message of the note.
     pub message: String,
 }
 
-#[derive(Clone, Debug, Hash, PartialOrd, Ord, PartialEq, Eq)]
+/// A Solidity diagnostic.
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct Diagnostic {
+    /// The code location of the diagnostic.
     pub loc: pt::Loc,
+    /// The level of the diagnostic.
     pub level: Level,
+    /// The type of diagnostic.
     pub ty: ErrorType,
+    /// The message of the diagnostic.
     pub message: String,
+    /// Extra notes about the diagnostic.
     pub notes: Vec<Note>,
 }
 
 impl Diagnostic {
+    /// Instantiate a new Diagnostic with the given location and message at the debug level.
     pub fn debug(loc: Loc, message: String) -> Self {
         Diagnostic {
             level: Level::Debug,
@@ -59,6 +92,7 @@ impl Diagnostic {
         }
     }
 
+    /// Instantiate a new Diagnostic with the given location and message at the info level.
     pub fn info(loc: Loc, message: String) -> Self {
         Diagnostic {
             level: Level::Info,
@@ -69,6 +103,7 @@ impl Diagnostic {
         }
     }
 
+    /// Instantiate a new parser error Diagnostic.
     pub fn parser_error(loc: Loc, message: String) -> Self {
         Diagnostic {
             level: Level::Error,
@@ -79,6 +114,7 @@ impl Diagnostic {
         }
     }
 
+    /// Instantiate a new syntax error Diagnostic.
     pub fn error(loc: Loc, message: String) -> Self {
         Diagnostic {
             level: Level::Error,
@@ -89,6 +125,7 @@ impl Diagnostic {
         }
     }
 
+    /// Instantiate a new declaration error Diagnostic.
     pub fn decl_error(loc: Loc, message: String) -> Self {
         Diagnostic {
             level: Level::Error,
@@ -99,6 +136,7 @@ impl Diagnostic {
         }
     }
 
+    /// Instantiate a new cast error error Diagnostic.
     pub fn cast_error(loc: Loc, message: String) -> Self {
         Diagnostic {
             level: Level::Error,
@@ -109,6 +147,7 @@ impl Diagnostic {
         }
     }
 
+    /// Instantiate a new cast error error Diagnostic, with a note.
     pub fn cast_error_with_note(loc: Loc, message: String, note_loc: Loc, note: String) -> Self {
         Diagnostic {
             level: Level::Error,
@@ -122,6 +161,7 @@ impl Diagnostic {
         }
     }
 
+    /// Instantiate a new type error error Diagnostic.
     pub fn type_error(loc: Loc, message: String) -> Self {
         Diagnostic {
             level: Level::Error,
@@ -132,6 +172,7 @@ impl Diagnostic {
         }
     }
 
+    /// Instantiate a new cast error Diagnostic at the warning level.
     pub fn cast_warning(loc: Loc, message: String) -> Self {
         Diagnostic {
             level: Level::Warning,
@@ -142,6 +183,7 @@ impl Diagnostic {
         }
     }
 
+    /// Instantiate a new warning Diagnostic.
     pub fn warning(loc: Loc, message: String) -> Self {
         Diagnostic {
             level: Level::Warning,
@@ -152,6 +194,7 @@ impl Diagnostic {
         }
     }
 
+    /// Instantiate a new warning Diagnostic, with a note.
     pub fn warning_with_note(loc: Loc, message: String, note_loc: Loc, note: String) -> Self {
         Diagnostic {
             level: Level::Warning,
@@ -165,6 +208,7 @@ impl Diagnostic {
         }
     }
 
+    /// Instantiate a new warning Diagnostic, with multiple notes.
     pub fn warning_with_notes(loc: Loc, message: String, notes: Vec<Note>) -> Self {
         Diagnostic {
             level: Level::Warning,
@@ -175,6 +219,7 @@ impl Diagnostic {
         }
     }
 
+    /// Instantiate a new error Diagnostic, with a note.
     pub fn error_with_note(loc: Loc, message: String, note_loc: Loc, note: String) -> Self {
         Diagnostic {
             level: Level::Error,
@@ -188,6 +233,7 @@ impl Diagnostic {
         }
     }
 
+    /// Instantiate a new error Diagnostic, with multiple notes.
     pub fn error_with_notes(loc: Loc, message: String, notes: Vec<Note>) -> Self {
         Diagnostic {
             level: Level::Error,