feat(cli)!: make documenting struct members optional (#32)

The default behavior has changed. Whereas before, struct members had to
be documented with `@param`, this is now optional and controlled with
the new `--struct-params` argument.

Author: beeb

.env.example

@@ -1,7 +1,8 @@
 LINTSPEC_PATHS=[path/to/file.sol,path/to/dir] # paths to files and folders to analyze
 LINTSPEC_EXCLUDE=[path/to/ignore] # paths to files or folders to exclude, see also `.nsignore`
-LINTSPEC_INHERITDOC=true   # enforce that all overridden, public and external items have `@inheritdoc`
-LINTSPEC_CONSTRUCTOR=false # enforce that constructors have natspec
-LINTSPEC_ENUM_PARAMS=false # enforce that enums have `@param` for each variant
-LINTSPEC_JSON=false        # output diagnostics as JSON
-LINTSPEC_COMPACT=false     # compact output (minified JSON or compact text)
+LINTSPEC_INHERITDOC=true     # enforce that all overridden, public and external items have `@inheritdoc`
+LINTSPEC_CONSTRUCTOR=false   # enforce that constructors have natspec
+LINTSPEC_STRUCT_PARAMS=false # enforce that structs have `@param` for each member
+LINTSPEC_ENUM_PARAMS=false   # enforce that enums have `@param` for each variant
+LINTSPEC_JSON=false          # output diagnostics as JSON
+LINTSPEC_COMPACT=false       # compact output (minified JSON or compact text)

.lintspec.toml

@@ -1,8 +1,9 @@
-paths = []          # paths to files and folders to analyze
-exclude = []        # paths to files or folders to exclude, see also `.nsignore`
-out = ""            # if provided, redirects output to this file
-inheritdoc = true   # enforce that all overridden, public and external items have `@inheritdoc`
-constructor = false # enforce that constructors have natspec
-enum_params = false # enforce that enums have `@param` for each variant
-json = false        # output diagnostics as JSON
-compact = false     # compact output (minified JSON or compact text)
+paths = []            # paths to files and folders to analyze
+exclude = []          # paths to files or folders to exclude, see also `.nsignore`
+out = ""              # if provided, redirects output to this file
+inheritdoc = true     # enforce that all overridden, public and external items have `@inheritdoc`
+constructor = false   # enforce that constructors have natspec
+struct_params = false # enforce that structs have `@param` for each member
+enum_params = false   # enforce that enums have `@param` for each variant
+json = false          # output diagnostics as JSON
+compact = false       # compact output (minified JSON or compact text)

README.md

@@ -72,6 +72,7 @@ Options:
   -o, --out <OUT>                    Write output to a file instead of stderr
       --inheritdoc                   Enforce that all public and external items have `@inheritdoc`
       --constructor                  Enforce that constructors have NatSpec
+      --struct-params                Enforce that structs have `@param` for each member
       --enum-params                  Enforce that enums have `@param` for each variant
       --json                         Output diagnostics in JSON format
       --compact                      Compact output
@@ -121,7 +122,12 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: beeb/lintspec@main
+        # all the lines below are optional
         with:
+          working-directory: "./"
+          paths: "[]"
+          exclude: "[]"
+          extra-args: ""
           version: "latest"
           fail-on-problem: "true"
 ```
@@ -168,11 +174,11 @@ Summary
 | Enforce usage of `@inheritdoc`  | ✅          | ✅                |
 | Enforce NatSpec on constructors | ✅          | ✅                |
 | Configure via config file       | ✅          | ✅                |
-| Enforce NatSpec on enums        | ✅          | ❌                |
+| Configure via env variables     | ✅          | ❌                |
 | Respects gitignore files        | ✅          | ❌                |
-| JSON output                     | ✅          | ❌                |
+| Enforce NatSpec on enums        | ✅          | ❌                |
 | Pretty output with code excerpt | ✅          | ❌                |
+| JSON output                     | ✅          | ❌                |
 | Output to file                  | ✅          | ❌                |
-| Configure via env variables     | ✅          | ❌                |
 | Multithreaded                   | ✅          | ❌                |
-| No pre-requisites (npm)         | ✅          | ❌                |
+| No pre-requisites (node/npm)    | ✅          | ❌                |

src/config.rs

@@ -42,6 +42,12 @@ pub struct Args {
     #[arg(long, num_args = 0..=1, default_missing_value = "true")]
     pub constructor: Option<bool>,
 
+    /// Enforce that structs have `@param` for each member
+    ///
+    /// Can be set with `--struct_params` (means true), `--struct_params true` or `--struct_params false`.
+    #[arg(long, num_args = 0..=1, default_missing_value = "true")]
+    pub struct_params: Option<bool>,
+
     /// Enforce that enums have `@param` for each variant
     ///
     /// Can be set with `--enum_params` (means true), `--enum_params true` or `--enum_params false`.
@@ -72,6 +78,7 @@ pub struct Config {
     pub out: Option<PathBuf>,
     pub inheritdoc: bool,
     pub constructor: bool,
+    pub struct_params: bool,
     pub enum_params: bool,
     pub json: bool,
     pub compact: bool,
@@ -85,6 +92,7 @@ impl From<Args> for Config {
             out: value.out,
             inheritdoc: value.inheritdoc.unwrap_or(true),
             constructor: value.constructor.unwrap_or_default(),
+            struct_params: value.enum_params.unwrap_or_default(),
             enum_params: value.enum_params.unwrap_or_default(),
             json: value.json.unwrap_or_default(),
             compact: value.compact.unwrap_or_default(),
@@ -101,6 +109,7 @@ pub fn read_config() -> Result<Config> {
             out: None,
             inheritdoc: None,
             constructor: None,
+            struct_params: None,
             enum_params: None,
             json: None,
             compact: None,
@@ -117,6 +126,9 @@ pub fn read_config() -> Result<Config> {
     if let Some(constructor) = args.constructor {
         temp.constructor = Some(constructor);
     }
+    if let Some(struct_params) = args.struct_params {
+        temp.struct_params = Some(struct_params);
+    }
     if let Some(enum_params) = args.enum_params {
         temp.enum_params = Some(enum_params);
     }

src/definitions/constructor.rs

@@ -106,6 +106,7 @@ mod tests {
     static OPTIONS: ValidationOptions = ValidationOptions {
         inheritdoc: false,
         constructor: true,
+        struct_params: false,
         enum_params: false,
     };
 

src/definitions/mod.rs

@@ -54,6 +54,12 @@ pub struct ValidationOptions {
     /// Whether to check that constructors have documented params
     pub constructor: bool,
 
+    /// Whether to check that each member of structs is documented with `@param`
+    ///
+    /// Not standard practice, the Solidity spec does not consider `@param` for structs or provide any other way to
+    /// document each member.
+    pub struct_params: bool,
+
     /// Whether to check that each variant of enums is documented with `@param`
     ///
     /// Not standard practice, the Solidity spec does not consider `@param` for enums or provide any other way to
@@ -67,6 +73,7 @@ impl Default for ValidationOptions {
         Self {
             inheritdoc: true,
             constructor: false,
+            struct_params: false,
             enum_params: false,
         }
     }
@@ -77,6 +84,7 @@ impl From<&Config> for ValidationOptions {
         Self {
             inheritdoc: value.inheritdoc,
             constructor: value.constructor,
+            struct_params: value.struct_params,
             enum_params: value.enum_params,
         }
     }

src/definitions/structure.rs

@@ -67,7 +67,7 @@ impl Validate for StructDefinition {
         .into())
     }
 
-    fn validate(&self, _: &ValidationOptions) -> ItemDiagnostics {
+    fn validate(&self, options: &ValidationOptions) -> ItemDiagnostics {
         let mut out = ItemDiagnostics {
             parent: self.parent(),
             item_type: ItemType::Struct,
@@ -83,7 +83,9 @@ impl Validate for StructDefinition {
             });
             return out;
         };
-        out.diags.append(&mut check_params(natspec, &self.members));
+        if options.struct_params {
+            out.diags = check_params(natspec, &self.members);
+        }
         out
     }
 }