docs: add documentation (#46)

* docs: add documentation

* docs: add documentation

* docs: add missing doc

* docs(config): add documentation

* docs: add documentation

* docs: add documentation

* docs: update readme

* docs: update readme

* docs: update readme

* docs: add documentation

* docs: update readme

Author: beeb

README.md

@@ -1,6 +1,6 @@
 # 🔎 lintspec
 
-![lintspec screenshot](./screenshot.png)
+![lintspec screenshot](https://raw.githubusercontent.com/beeb/lintspec/refs/heads/main/screenshot.png)
 
 <div align="center">
   <a href="https://github.com/beeb/lintspec"><img
@@ -61,7 +61,7 @@ Head over to the [releases page](https://github.com/beeb/lintspec/releases)!
 
 ## Usage
 
-```
+```text
 Usage: lintspec [OPTIONS] [PATH]...
 
 Arguments:
@@ -101,16 +101,16 @@ that are displayed in the source files when viewed (e.g. in a PR's "Files" tab).
 
 ### Options
 
-The following options are available for the action (all are optional):
+The following options are available for the action (all are optional if a config file is present):
 
 | Input | Default Value | Description | Example |
 |---|---|---|---|
 | `working-directory` | `"./"` | Working directory path | `"./src"` |
-| `paths` | `"[]"` | Paths to scan, relative to the working directory, in square brackets and separated by commas. | `"[path/to/file.sol,test/test.sol]"` |
+| `paths` | `"[]"` | Paths to scan, relative to the working directory, in square brackets and separated by commas. Required unless a `.lintspec.toml` file is present in the working directory. | `"[path/to/file.sol,test/test.sol]"` |
 | `exclude` | `"[]"` | Paths to exclude, relative to the working directory, in square brackets and separated by commas | `"[path/to/exclude,other/path.sol]"` | 
 | `extra-args` | | Extra arguments passed to the `lintspec` command | `"--constructor=true"` |
 | `version` | `"latest"` | Version of lintspec to use. For enhanced security, you can pin this to a fixed version | `"0.1.5"` |
-| `fail-on-problem` | `"true"` | Whether the action should fail when NatSpec problems have been found. Disabling this only creates annotations for found problems, but succeeds | `"false"` |
+| `fail-on-problem` | `"true"` | Whether the action should fail when `NatSpec` problems have been found. Disabling this only creates annotations for found problems, but succeeds | `"false"` |
 
 ### Example Workflow
 
@@ -149,7 +149,7 @@ On an AMD Ryzen 9 7950X processor with 64GB of RAM, linting the
 [Uniswap/v4-core](https://github.com/Uniswap/v4-core) `src` folder on WSL2 (Ubuntu), lintspec is about 214x faster, or
 0.46% of the execution time:
 
-```
+```text
 Benchmark 1: npx @defi-wonderland/natspec-smells --include "src/**/*.sol"
   Time (mean ± σ):     12.484 s ±  0.157 s    [User: 13.581 s, System: 0.594 s]
   Range (min … max):   12.288 s … 12.817 s    10 runs

src/config.rs

@@ -1,3 +1,4 @@
+//! Tool configuration parsing and validation
 use std::path::PathBuf;
 
 use anyhow::Result;
@@ -91,21 +92,43 @@ pub struct Args {
     pub sort: Option<bool>,
 }
 
+/// The parsed and validated config for the tool
 #[derive(Debug, Clone, Serialize, Deserialize, bon::Builder)]
 #[non_exhaustive]
 #[builder(on(PathBuf, into))]
 #[allow(clippy::struct_excessive_bools)]
 pub struct Config {
+    /// The paths to search for Solidity files
     pub paths: Vec<PathBuf>,
+
+    /// Some paths to ignore while searching for Solidity files
     pub exclude: Vec<PathBuf>,
+
+    /// The file where to output the diagnostics (if `None`, then stderr is used)
     pub out: Option<PathBuf>,
+
+    /// Whether to enforce the use of `@inheritdoc` on external/public/overridden items
     pub inheritdoc: bool,
+
+    /// Whether to enforce documentation of constructors
     pub constructor: bool,
+
+    /// Whether to enforce documentation of struct members
     pub struct_params: bool,
+
+    /// Whether to enforce documentation of enum variants
     pub enum_params: bool,
+
+    /// Whether to enforce documentation of items which have no params/returns/members
     pub enforce: Vec<ItemType>,
+
+    /// Output JSON diagnostics
     pub json: bool,
+
+    /// Output compact format (minified JSON or simple text output)
     pub compact: bool,
+
+    /// Sort diagnostics by file path
     pub sort: bool,
 }
 

src/definitions/constructor.rs

@@ -1,3 +1,4 @@
+//! Parsing and validation of constructors.
 use slang_solidity::cst::{NonterminalKind, Query, QueryMatch, TextRange};
 
 use crate::{
@@ -15,9 +16,16 @@ use super::{
 #[derive(Debug, Clone, bon::Builder)]
 #[non_exhaustive]
 pub struct ConstructorDefinition {
+    /// The parent contract (should always be a [`Parent::Contract`])
     pub parent: Option<Parent>,
+
+    /// The span corresponding to the constructor definition, excluding the body
     pub span: TextRange,
+
+    /// The name and span of the constructor's parameters
     pub params: Vec<Identifier>,
+
+    /// The [`NatSpec`] associated with the constructor, if any
     pub natspec: Option<NatSpec>,
 }
 

src/definitions/enumeration.rs

@@ -1,3 +1,4 @@
+//! Parsing and validation of enum definitions.
 use slang_solidity::cst::{Cursor, Query, QueryMatch, TerminalKind, TextRange};
 
 use crate::{
@@ -16,10 +17,19 @@ use super::{
 #[non_exhaustive]
 #[builder(on(String, into))]
 pub struct EnumDefinition {
+    /// The parent for the enum definition, if any
     pub parent: Option<Parent>,
+
+    /// The name of the enum
     pub name: String,
+
+    /// The span of the enum definition
     pub span: TextRange,
+
+    /// The name and span of the enum variants
     pub members: Vec<Identifier>,
+
+    /// The [`NatSpec`] associated with the enum definition, if any
     pub natspec: Option<NatSpec>,
 }
 
@@ -94,6 +104,7 @@ impl Validate for EnumDefinition {
     }
 }
 
+/// Extract the identifiers of each of an enum's variants
 fn extract_enum_members(cursor: &Cursor) -> Vec<Identifier> {
     let mut cursor = cursor.spawn().with_edges();
     let mut out = Vec::new();

src/definitions/error.rs

@@ -1,3 +1,4 @@
+//! Parsing and validation of error definitions.
 use slang_solidity::cst::{Query, QueryMatch, TextRange};
 
 use crate::{
@@ -16,10 +17,19 @@ use super::{
 #[non_exhaustive]
 #[builder(on(String, into))]
 pub struct ErrorDefinition {
+    /// The parent for the error definition, if any
     pub parent: Option<Parent>,
+
+    /// The name of the error
     pub name: String,
+
+    /// The span of the error definition
     pub span: TextRange,
+
+    /// The name and span of the error's parameters
     pub params: Vec<Identifier>,
+
+    /// The [`NatSpec`] associated with the error definition, if any
     pub natspec: Option<NatSpec>,
 }
 

src/definitions/event.rs

@@ -1,3 +1,4 @@
+//! Parsing and validation of event definitions.
 use slang_solidity::cst::{NonterminalKind, Query, QueryMatch, TextRange};
 
 use crate::{
@@ -16,10 +17,19 @@ use super::{
 #[non_exhaustive]
 #[builder(on(String, into))]
 pub struct EventDefinition {
+    /// The parent for the event definition, if any
     pub parent: Option<Parent>,
+
+    /// The name of the event
     pub name: String,
+
+    /// The span of the event definition
     pub span: TextRange,
+
+    /// The name and span of the event's parameters
     pub params: Vec<Identifier>,
+
+    /// The [`NatSpec`] associated with the event definition, if any
     pub natspec: Option<NatSpec>,
 }
 

src/definitions/function.rs

@@ -1,3 +1,4 @@
+//! Parsing and validation of function definitions.
 use slang_solidity::cst::{NonterminalKind, Query, QueryMatch, TextRange};
 
 use crate::{
@@ -17,12 +18,25 @@ use super::{
 #[non_exhaustive]
 #[builder(on(String, into))]
 pub struct FunctionDefinition {
+    /// The parent for the function definition (should always be `Some`)
     pub parent: Option<Parent>,
+
+    /// The name of the function
     pub name: String,
+
+    /// The span of the function definition, exluding the body
     pub span: TextRange,
+
+    /// The name and span of the function's parameters
     pub params: Vec<Identifier>,
+
+    /// The name and span of the function's returns
     pub returns: Vec<Identifier>,
+
+    /// The [`NatSpec`] associated with the function definition, if any
     pub natspec: Option<NatSpec>,
+
+    /// The attributes of the function (visibility and override)
     pub attributes: Attributes,
 }
 

src/definitions/mod.rs

@@ -1,3 +1,10 @@
+//! Parsing and validation of source item definitions
+//!
+//! This module contains structs for each of the source item types that can be documented with `NatSpec`.
+//! The [`Definition`] type provides a unified interface to interact with the various types.
+//! The [`find_items`] function takes the tree root [`Cursor`] from a Solidity document and returns all the parsed
+//! definitions contained within.
+//! Some helper functions allow to extract useful information from [`Cursor`]s.
 use constructor::ConstructorDefinition;
 use derive_more::{Display, From};
 use enumeration::EnumDefinition;
@@ -304,7 +311,7 @@ impl Definition {
     }
 }
 
-/// Find source item definitions from a root CST cursor
+/// Find source item definitions from a root CST [`Cursor`]
 pub fn find_items(cursor: Cursor) -> Vec<Definition> {
     let mut out = Vec::new();
     for m in cursor.query(vec![
@@ -357,7 +364,7 @@ pub fn find_items(cursor: Cursor) -> Vec<Definition> {
 
 /// Extract parameters from a function-like source item.
 ///
-/// The node kind that holds the `Identifier` (`Parameter`, `EventParameter`) is provided as `kind`.
+/// The node kind that holds the `Identifier` (`Parameter`, `EventParameter`) must be provided with `kind`.
 #[must_use]
 pub fn extract_params(cursor: &Cursor, kind: NonterminalKind) -> Vec<Identifier> {
     let mut cursor = cursor.spawn();
@@ -474,6 +481,60 @@ pub fn extract_identifiers(cursor: &Cursor) -> Vec<Identifier> {
     out
 }
 
+/// Extract the attributes (visibility and override) from a function-like item or state variable
+#[must_use]
+pub fn extract_attributes(cursor: &Cursor) -> Attributes {
+    let mut cursor = cursor.spawn();
+    let mut out = Attributes::default();
+    while cursor.go_to_next_terminal_with_kinds(&[
+        TerminalKind::ExternalKeyword,
+        TerminalKind::InternalKeyword,
+        TerminalKind::PrivateKeyword,
+        TerminalKind::PublicKeyword,
+        TerminalKind::OverrideKeyword,
+    ]) {
+        match cursor
+            .node()
+            .as_terminal()
+            .expect("should be terminal kind")
+            .kind
+        {
+            TerminalKind::ExternalKeyword => out.visibility = Visibility::External,
+            TerminalKind::InternalKeyword => out.visibility = Visibility::Internal,
+            TerminalKind::PrivateKeyword => out.visibility = Visibility::Private,
+            TerminalKind::PublicKeyword => out.visibility = Visibility::Public,
+            TerminalKind::OverrideKeyword => out.r#override = true,
+            _ => unreachable!(),
+        }
+    }
+    out
+}
+
+/// Find the parent's name (contract, interface, library), if any
+#[must_use]
+pub fn extract_parent_name(mut cursor: Cursor) -> Option<Parent> {
+    while cursor.go_to_parent() {
+        if let Some(parent) = cursor.node().as_nonterminal_with_kinds(&[
+            NonterminalKind::ContractDefinition,
+            NonterminalKind::InterfaceDefinition,
+            NonterminalKind::LibraryDefinition,
+        ]) {
+            for child in &parent.children {
+                if child.is_terminal_with_kind(TerminalKind::Identifier) {
+                    let name = child.node.unparse().trim().to_string();
+                    return Some(match parent.kind {
+                        NonterminalKind::ContractDefinition => Parent::Contract(name),
+                        NonterminalKind::InterfaceDefinition => Parent::Interface(name),
+                        NonterminalKind::LibraryDefinition => Parent::Library(name),
+                        _ => unreachable!(),
+                    });
+                }
+            }
+        }
+    }
+    None
+}
+
 /// Check a list of params to see if they are documented with a corresponding item in the [`NatSpec`], and generate a
 /// diagnostic for each missing one or if there are more than 1 entry per param.
 #[must_use]
@@ -542,60 +603,6 @@ pub fn check_returns(
     res
 }
 
-/// Extract the attributes (visibility and override) from a function-like item or state variable
-#[must_use]
-pub fn extract_attributes(cursor: &Cursor) -> Attributes {
-    let mut cursor = cursor.spawn();
-    let mut out = Attributes::default();
-    while cursor.go_to_next_terminal_with_kinds(&[
-        TerminalKind::ExternalKeyword,
-        TerminalKind::InternalKeyword,
-        TerminalKind::PrivateKeyword,
-        TerminalKind::PublicKeyword,
-        TerminalKind::OverrideKeyword,
-    ]) {
-        match cursor
-            .node()
-            .as_terminal()
-            .expect("should be terminal kind")
-            .kind
-        {
-            TerminalKind::ExternalKeyword => out.visibility = Visibility::External,
-            TerminalKind::InternalKeyword => out.visibility = Visibility::Internal,
-            TerminalKind::PrivateKeyword => out.visibility = Visibility::Private,
-            TerminalKind::PublicKeyword => out.visibility = Visibility::Public,
-            TerminalKind::OverrideKeyword => out.r#override = true,
-            _ => unreachable!(),
-        }
-    }
-    out
-}
-
-/// Find the parent's name (contract, interface, library), if any
-#[must_use]
-pub fn extract_parent_name(mut cursor: Cursor) -> Option<Parent> {
-    while cursor.go_to_parent() {
-        if let Some(parent) = cursor.node().as_nonterminal_with_kinds(&[
-            NonterminalKind::ContractDefinition,
-            NonterminalKind::InterfaceDefinition,
-            NonterminalKind::LibraryDefinition,
-        ]) {
-            for child in &parent.children {
-                if child.is_terminal_with_kind(TerminalKind::Identifier) {
-                    let name = child.node.unparse().trim().to_string();
-                    return Some(match parent.kind {
-                        NonterminalKind::ContractDefinition => Parent::Contract(name),
-                        NonterminalKind::InterfaceDefinition => Parent::Interface(name),
-                        NonterminalKind::LibraryDefinition => Parent::Library(name),
-                        _ => unreachable!(),
-                    });
-                }
-            }
-        }
-    }
-    None
-}
-
 #[cfg(test)]
 mod tests {
     use similar_asserts::assert_eq;