Add @param in default template

[Pzixel]

1. git clone https://github.com/Uniswap/uniswap-v3-core.git --depth 1
2. cd uniswap-v3-core
3. npx solidity-docgen --solc-module solc-0.7

Then let's check some file. I've took IUniswapV3Factory.sol as example.

This is how item is documented:

    /// @notice Creates a pool for the given two tokens and fee
    /// @param tokenA One of the two tokens in the desired pool
    /// @param tokenB The other of the two tokens in the desired pool
    /// @param fee The desired fee for the pool
    /// @dev tokenA and tokenB may be passed in either order: token0/token1 or token1/token0. tickSpacing is retrieved
    /// from the fee. The call will revert if the pool already exists, the fee is invalid, or the token arguments
    /// are invalid.
    /// @return pool The address of the newly created pool
    function createPool(
        address tokenA,
        address tokenB,
        uint24 fee
    ) external returns (address pool);

And this is actual result of npx solidity-docgen output:

### `createPool(address tokenA, address tokenB, uint24 fee) → address pool` (external)

Creates a pool for the given two tokens and fee


tokenA and tokenB may be passed in either order: token0/token1 or token1/token0. tickSpacing is retrieved
from the fee. The call will revert if the pool already exists, the fee is invalid, or the token arguments
are invalid.

You can see that only notice message got rendered.

Expected result:

# Function `createPool(address tokenA, address tokenB, uint24 fee) → address pool`  (external) {#IUniswapV3Factory-createPool-address-address-uint24-}

Creates a pool for the given two tokens and fee

tokenA and tokenB may be passed in either order: token0/token1 or token1/token0. tickSpacing is retrieved from the fee. The call will revert if the pool already exists, the fee is invalid, or the token arguments are invalid.

## Parameters:

- `tokenA`: One of the two tokens in the desired pool

- `tokenB`: The other of the two tokens in the desired pool

- `fee`: The desired fee for the pool

## Return Values:

- pool The address of the newly created pool

Used version: solidity-docgen/0.5.13 win32-x64 node-v16.0.0

---

I'm not sure how you're using solc internally (as I asked in another comment out there) but from what I've seen it only returns some comments in --devdoc and some only in --userdoc, so I'd propose tool to merge calls to both (possibly behind similarly named flags?)

[frangio]

You can set a template to customize the output. Copy contract.hbs into a templates directory, then call solidity-docgen -t templates ...

All of the information you want is available in the template. You can find some examples and WIP documentation in #290.

[Pzixel]

Okay, I see. Thanks. Anyway, I'd propose to use more user-friendly template as default (when one comes live).

Thanks for a quick answer, as always!

[frangio]

I agree that parameters should be included by default. Would appreciate a PR if you wanted to provide one!

[Pzixel]

I'm working on it right now. Could you also help me with following: how do I add contract description in hbs template? I'm lurking at https://github.com/OpenZeppelin/solidity-docgen/blob/9bd50c32841d1e9500fa35fce48dc541d72cd8bb/src/source.ts but didn't find a way to do so. For example:

/// @title Prevents delegatecall to a contract
/// @notice Base contract that provides a modifier for preventing delegatecall to methods in a child contract
abstract contract NoDelegateCall {
}

I'd like to get this comment to output

[frangio]

@notice corresponds to `{{natspec.userdoc}}``.

{{title}}

{{natspec.userdoc}}

[Evert0x]

Hey @Pzixel, I see you got the .hb file working with the @param natspec here

Do you mind sharing your handlebar file?

[Pzixel]

Hey. Why not I guess. There is only one caveat: I have two versions to work with readthedocs (rst) and gitbook(md). The former requires some postprocessing to make it work but if you're fine with gitbook you probably don't need anything. This is my template:

# {{{name}}}

{{{title}}}
{{{natspec.userdoc}}}
{{{natspec.devdoc}}}

{{#if ownFunctions}}
## Functions
{{/if}}

{{#ownFunctions}}
### `{{name}}({{args}}){{#if outputs}} → {{outputs}}{{/if}}`
{{#if natspec.devdoc}}{{natspec.devdoc}}{{else}}No description{{/if}}

{{#if natspec.params}}
#### Parameters:
{{#natspec.params}}
- `{{param}}`: {{description}}
{{/natspec.params}}
{{/if}}
{{#if natspec.returns}}
#### Return Values:
{{#natspec.returns}}
- {{param}} {{description}}
{{/natspec.returns}}
{{/if}}

{{/ownFunctions}}


{{#if ownEvents}}
## Events
{{/if}}

{{#ownEvents}}
### `{{name}}({{args}})`
{{#if natspec.devdoc}}{{natspec.devdoc}}{{else}}No description{{/if}}

{{#if natspec.params}}
#### Parameters:
{{#natspec.params}}
- `{{param}}`: {{description}}
{{/natspec.params}}
{{/if}}
{{/ownEvents}}

Hope this helps!

[Evert0x]

Thanks a lot! Made me realize using comments like

/**
    @notice 
    @param 
    @return 
  */

Doesn't work, has to be written like

  /// @notice 
  /// @param 
  /// @return

[frangio]

@Pzixel Thank you for sharing! Is the setup with Gitbook available in a public repo? I'd love to see.

[Pzixel]

AFAIK it's going to be published soonish but not quite yet. So unfortunately I cannot share it right now.