Update NatSpec examples for consistency

[fulldecent]

Regarding file https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format

That natspec spec doesn't really specify whether or not periods are required or not, including giving multiple contradictory examples and unspecified multiline specifications

/// @notice (balanceInmGAV / 1000).fixed(0,3) GAV is the total funds available to who.address().

Also in this spec document are

/// @notice Enable or disable approval for a third party ("operator") to manage
/// all of msg.sender's assets.

and

/// @notice A distinct Uniform Resource Identifier (URI) for a given asset.

along with inconsistent periods at the end of @param tags like

/// @param _operator Address to add to the set of authorized operators.

We want the rule: "no trailing periods except on @dev tags".

Work plan

• State this rule
• Update examples in the wiki to follow that rule

---

Credit to @shrugs at ethereum/EIPs#1151 (comment)

---

Discussion: I support this change because I expect that the notice and param tags will be shown in MetaMask one day. Just imagining how the user interface might look, it will be a form with a name, the value, and a descriptor text for each field. I think in general you don't need a period. Here is how it might look.

[jamesray1]

I think if the notice is a complete sentence it can have a period but generally these descriptions are not complete sentences, and rewriting them like that makes them more verbose when it is obvious what they are referring to. E.g. "Address to add to the set of authorized operators." could be rewritten to "address to add to the set of authorized operators" or, "This is the address to add to the set of authorized operators." The latter is more verbose, and while more grammatically correct, isn't necessary when it is obvious what the description is referring to.

[jamesray1]

Maybe try to contact some NatSpec implementers and reach a consensus with them. I don't think it matters with the context of what the tag is or whether there is even a tag. Use either of the forms: "address to add to the set of authorized operators" or, "This is the address to add to the set of authorized operators."; depending on the context. It doesn't seem to matter whether it's multiline, just as long as the structure and meaning are clear it should be OK, IMO.