Natspec: text before the @notice tag gets included as part of it

[axic]

contract C {
  /// Before the notice.
  /// @notice Some function.
  function f() public view returns (uint ret) {
  }
}

results in

Developer Documentation
{
  "kind": "dev",
  "methods": {},
  "version": 1
}
User Documentation
{
  "kind": "user",
  "methods":
  {
    "f()":
    {
      "notice": "Before the notice.Some function."
    }
  },
  "version": 1
}

[axic]

Also text after the notice tag is included no matter how many empty lines:

contract C {
  /// Before the notice.
  /// @notice Some function.
  ///
  ///
  ///
  /// After the notice.
  function f() public view returns (uint ret) {
  }
}

Developer Documentation
{
  "kind": "dev",
  "methods": {},
  "version": 1
}
User Documentation
{
  "kind": "user",
  "methods":
  {
    "f()":
    {
      "notice": "Before the notice.Some function. After the notice."
    }
  },
  "version": 1
}

Inserting a tag between the notice and trailing text works as expected (well, the text on the new line is also part of `@return):

contract C {
  /// Before the notice.
  /// @notice Some function.
  ///
  ///
  ///
  /// @return ret something
  /// After the notice.
  function f() public view returns (uint ret) {
  }
}

Developer Documentation
{
  "kind": "dev",
  "methods":
  {
    "f()":
    {
      "returns":
      {
        "ret": "something After the notice."
      }
    }
  },
  "version": 1
}
User Documentation
{
  "kind": "user",
  "methods":
  {
    "f()":
    {
      "notice": "Before the notice.Some function."
    }
  },
  "version": 1
}

I start to think this is by design :)

[hrkrshnn]

I think the rule is that NatSpec comment without a tag is assumed to be notice. That explains all the above situations.

[axic]

Why do we have @notice then? It seems to be confusing.

Can we remove @notice and say that every untagged natspec comment is included as a "comment" field?

However what happens in the case where there comments and tags intermixed. Are all the comments concatenated together?

[hrkrshnn]

I wasn't there when this was designed. My guess is that the no-tag -> notice was done so that existing /// doesn't break.

I think removing @notice might be too much now, since that will break a lot of contracts. Maybe removing comments without tags might make more sense.

[chriseth]

I think you can have

@dev bla
@notice blu

But probably we should disallow @notice if there is already untagged text in front of it.

[axic]

We had a discussion about this on today's meeting.

Currently any untagged content (i.e. /// Hello world) defaults to @notice. Multiple tagged or untagged @notices are concatenated together.

The question we had whether untagged comments are for the user or the developer. If they are for the developer, then we should have the following rules:

• Only one @notice tag is allowed, and it is exported for the user documentation.
• Remove @dev. Anything untagged is concatenated and exported as "dev documentation`.

[hrkrshnn]

I think the current behaviour is fine. Disallowing multiple notice, I think is not nice, in situations like these:

/// @notice long paragraph on contract
///
/// @notice another long paragraph on contract.
contract C {
}

However, currently this gets parsed as "notice": "long paragraph on contractanother long paragraph",. Probably missing a space.

[devtooligan]

I support the current behavior.

imo assuming the top /// lines without tags are @notice is a feature not a bug.

Ever since I learned about this I've stopped using the @notice in most cases and imo the code looks so much cleaner now.

It also adds to the conversation of should you try and indent your multi-line natspec comments since a lot of multi-line comments are @notice so if you skip the tag then it is aligned to the left.

contract MyContract {

  /// This is a multiline comment and it looks so nice aligned to the left, 
  /// also now I don't need to think about whether or not I should indent
  /// the lines after the first to align the first characters.
  /// @param x This is the amount of the param.
  /// @param y This is the other amount of the param.
  /// function myFunction(uint256 x, uint256 y) public {...}
}