A recent commit to EIP-8182 clarifies the resolution mechanism for importing Natspec documentation, improving developer experience and tooling integration.

> impact

EIP-8182, which standardizes how Natspec documentation can be imported from external contracts, has received a key update. The proposal allows developers to pull in documentation for interfaces, libraries, and inherited contracts using an `@import` tag, similar to how Solidity handles code imports. The latest commit specifically addresses ambiguities in path resolution, defining a clear lookup order for dependencies, starting from local project files and extending to installed packages (e.g., node_modules/@openzeppelin). The primary motivation behind this update is to enhance code clarity and reduce documentation redundancy. Currently, developers often copy-paste Natspec comments from an interface or parent contract into their implementation, which is error-prone and difficult to maintain. By creating a standardized import mechanism, EIP-8182 allows documentation to live in a single canonical source. This change ensures that development environments, static analysis tools, and documentation generators can consistently locate and render the correct documentation, making complex codebases more navigable and auditable. The impact on the developer ecosystem is significant. Once adopted by tooling providers, this EIP will enable IDEs like VS Code and Remix to provide richer inline documentation and hover-over information for functions defined in external interfaces. Documentation generators can build more comprehensive and accurate site outputs automatically, and block explorers could even use it to display verified source code with complete, inherited Natspec. This standardization simplifies the developer workflow, improves the quality of on-chain contract documentation, and fosters a more transparent and understandable development environment.

> Try this now

try this

/*
  EIP-8182 introduces a new Natspec tag, `@import`, for inheriting documentation.
  Below is a conceptual walkthrough demonstrating how to use it.

  File: ./IERC20.sol
*/

// 1. First, define an interface with rich Natspec comments.
//    This serves as the canonical source for the documentation.
interface IERC20 {
    /**
     * @notice Moves `amount` tokens from the caller's account to `recipient`.
     * @param recipient The address which will receive the tokens.
     * @param amount The amount of tokens to be transferred.
     * @return A boolean value indicating whether the operation succeeded.
     */
    function transfer(address recipient, uint256 amount) external returns (bool);
}

/*
  File: ./MyToken.sol
*/

import "./IERC20.sol";

// 2. In your implementing contract, you can now import Natspec.
contract MyToken is IERC20 {
    // 3. Use the `@import` tag to pull in the full documentation for the `transfer` function
    //    from the IERC20 interface. Tooling that supports EIP-8182 will now
    //    display the detailed Natspec from IERC20.sol when referencing MyToken.sol's transfer function.
    /// @import {transfer} from "./IERC20.sol";
    function transfer(address recipient, uint256 amount) external override returns (bool) {
        // Your implementation logic here...
        return true;
    }
}