Lintspec is a free, open-source command-line linter that checks the completeness and validity of NatSpec doc-comments in Solidity code. It is built for smart contract developers who want their documentation to stay consistent and complete as codebases grow, especially teams that publish contracts or rely on generated docs.
The tool is written in Rust and focuses on two things: speed and ergonomics. It scans your Solidity files, reports missing or malformed NatSpec tags, and fits into a normal development workflow without a heavy setup. By default, it respects gitignore rules when looking for source files, so dependencies and build artifacts are skipped automatically.
What Is NatSpec and Why Does It Matter?
NatSpec is the documentation format used in Solidity to describe contracts, functions, events and state variables. Tags such as @notice, @dev, @param and @return are written as special comments directly above the code they describe. Tools and block explorers can read these comments to show users what a function does and what its inputs mean.
When NatSpec is incomplete or inconsistent, the impact goes beyond style. A missing @param tag makes an interface harder to audit, and a stale @notice can mislead anyone integrating with the contract. A linter turns documentation into a checkable part of the build rather than a manual review item.
Who Is Lintspec For?
Lintspec is aimed at Solidity developers, auditing teams and maintainers of open-source protocols. Solo developers can use it to keep their own contracts tidy before publishing. Larger teams can add it to continuous integration so that every pull request is checked against the same documentation rules.
It is also useful for anyone who inherits a large codebase with uneven comments. Running the linter once gives a clear list of gaps to close, which is often more practical than reviewing every file by hand.
How Linting Fits Into a Solidity Workflow
Most Solidity projects already use a compiler, a test framework and often a formatter. A NatSpec linter sits alongside these tools and checks a different property: whether the comments describe the code accurately and completely. Because Lintspec is a command-line program, it can be run locally before a commit or automatically in a pipeline.
A common pattern is to run the linter with the same rules across the whole repository and then tighten requirements over time. Starting with @notice and @param on public functions and expanding from there keeps the workload manageable.
Key features
Configurable NatSpec Validation
Flexible Notice and Dev Handling
Gitignore-Aware Scanning
Selectable Parser Backends
How to install Lintspec on Windows
- 1
Download the Program
Get the latest release from the official GitHub repository at https://github.com/beeb/lintspec. Look for the Releases section and download the Windows build if one is listed for the current version. Download only from the official website or the project's GitHub page.
- 2
Verify the File
Before running the program, check the SHA-256 checksum of the downloaded file against the value published with the release, if one is provided. If the release includes a signature, verify it as well. A mismatch means the file should not be used.
- 3
Place the Executable
Move the executable to a folder you control, such as a tools directory inside your user profile, and add that folder to your PATH if you want to run lintspec from any terminal window.
-
Confirm the Installation
Open Command Prompt or PowerShell and run the program with its help flag to confirm that it starts and lists the available options. If Windows reports that the file is not recognized, check the PATH setting and the file name.
How to use Lintspec
Lintspec runs from the command line. Once you have the executable available, you point it at a Solidity project and choose which NatSpec rules to enforce. A typical session takes only a few seconds, even on large repositories.
A simple workflow looks like this:
- Open a terminal and navigate to the root of your Solidity project.
- Run lintspec with the help flag to review the available options and required-tag settings.
- Decide which tags are mandatory for each item type, for example @notice for public functions and @param for function arguments.
- Run the linter and read the report, which lists the file, line and missing or invalid tag.
- Fix the reported comments and run the linter again until the output is clean.
- Add the same command to your continuous integration configuration so that new code is checked automatically.
Pros & cons
- Fast, Rust-based implementation suited to large repositories
- Respects gitignore rules by default
- Fine-grained control over which NatSpec tags are required
- Free and released under the permissive MIT license
- Simple command-line interface that is easy to script
- The official project metadata lists Linux as the primary platform, so Windows support should be confirmed in the current release notes
- Focused on NatSpec only; it does not replace a full Solidity linter or security analyzer
- Requires comfort with the command line and project-level configuration
- Documentation checks cannot judge whether a comment is correct, only whether it is present and well formed
Is Lintspec safe?
Lintspec is open-source software distributed under the MIT license, and its code is publicly available on GitHub. To reduce risk, download the program only from the official repository, check the SHA-256 checksum or signature when the release provides one, and avoid copies from unofficial mirrors. Because the tool reads your source files, it is also worth running it on a copy of a project first if you are unsure how it behaves. Antivirus software may occasionally flag newly built command-line tools; if that happens, verify the file's checksum rather than disabling your protection. Always check the latest version on the official website before installing.
- Official source only. Download from github.com/beeb/lintspec. Ignore ads and lookalike domains.
- Check the SHA-256. Compare the installer hash with the value the developer publishes before running it.
- Never share your seed phrase. No developer, support agent or website — including CryptApps — will ever ask for it.
Alternatives
Lintspec differs from broader Solidity tooling in its narrow focus. Remix Desktop and Visual Studio Code with Solidity extensions are development environments that can display warnings while you edit, which is convenient for writing comments interactively. Lintspec is better suited to automated checks in a terminal or pipeline, where the same rules are applied to every file in the repository.
Compared with Foundry, which bundles a compiler, test runner and deployment tools, Lintspec does one job. Teams that already use Foundry often run Lintspec alongside it rather than instead of it. Developers who want a broader suite of contract analysis may combine it with tools such as Tenderly CLI for debugging and monitoring.
Specifications
- Price
- Free
- Type
- Open source
- License
- MIT
- Latest version
- v0.19.0
- Last update
- 23 Sept 2026
- Windows support
- Likely (builds for Windows; check releases)
- Source code
- github.com/beeb/lintspec
Frequently asked questions
Yes. Lintspec is free and open source, released under the MIT license. You can use it in personal and commercial projects, and the source code is available on GitHub for review and modification.
Lintspec checks NatSpec doc-comments in Solidity code. It verifies that required tags such as @notice, @dev, @param, @title and @author are present for the item types you specify, and it reports comments that are missing or malformed.
The project metadata lists Linux as the primary platform and notes that Windows builds may be available. Check the current GitHub Releases page for a Windows binary, or build from source if your environment supports it.
Yes. By default, Lintspec follows gitignore rules when searching for Solidity source files, so ignored directories and generated files are skipped unless you change that behavior.
Lintspec offers two parser backends, solar and slang. Solar is the default and is enabled out of the box. Slang is an alternative backend you can select if it matches your toolchain or project preferences.
Yes. Because it is a command-line tool, Lintspec can run in continuous integration jobs. You can configure it to fail the build when required NatSpec tags are missing, keeping documentation standards consistent across pull requests.
No. The linter confirms that required tags exist and are well formed, but it cannot judge whether the wording matches the code. Accuracy still requires human review and good testing practices.
It is an open-source linter that reads source files and reports results. Download it only from the official GitHub repository, verify the checksum or signature when available, and review the source if your organization requires it.
Verdict
Lintspec is a focused, fast and free tool for Solidity developers who want consistent NatSpec documentation. It suits teams with clear documentation standards and projects that run checks in automated pipelines. If you need a full analysis suite, pair it with a compiler, test framework or security tool rather than expecting it to cover everything.