ethereum / solidity

Solidity, the Smart Contract Programming Language
https://soliditylang.org
GNU General Public License v3.0
22.64k stars 5.61k forks source link

Update Natspec format to correct devdoc return parameters #15187

Open shoenseiwaso opened 3 weeks ago

shoenseiwaso commented 3 weeks ago

Update the Natspec documentation to match what solc outputs for devdoc return parameters.

Consider the following minimal smart contract with documented Natspec devdoc return parameters:

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.0;

contract ReturnsDocs {
    /// @return A number
    function returnOne() public pure returns (uint) {
        return 1;
    }

    /// @return A number
    /// @return A string
    function returnTwo() public pure returns (uint, string memory) {
        return (2, "two");
    }
}

Compiling with devdoc output:

$ solc --combined-json devdoc ReturnDocs.sol | jq

{
  "contracts": {
    "ReturnDocs.sol:ReturnsDocs": {
      "devdoc": {
        "kind": "dev",
        "methods": {
          "returnOne()": {
            "returns": {
              "_0": "A number"
            }
          },
          "returnTwo()": {
            "returns": {
              "_0": "A number",
              "_1": "A string"
            }
          }
        },
        "version": 1
      }
    }
  },
  "version": "0.8.26+commit.8a97fa7a.Darwin.appleclang"
}
github-actions[bot] commented 3 weeks ago

Thank you for your contribution to the Solidity compiler! A team member will follow up shortly.

If you haven't read our contributing guidelines and our review checklist before, please do it now, this makes the reviewing process and accepting your contribution smoother.

If you have any questions or need our help, feel free to post them in the PR or talk to us directly on the #solidity-dev channel on Matrix.