Slogan could be improved

[fulldecent]

"Radspec is a safe alternative to Ethereum's natspec"

Reading more it seems like Radspec is a (safe) implementation of NatSpec.

Of course, the last thing we need is fragmentation in the ABI commenting standard.

[sohkai]

Of course, the last thing we need is fragmentation in the ABI commenting standard.

There's not really any room for this, since solidity will complain if you don't format the comments properly. And AFAIK, there's no other comment parsers available out there that a frontend can use to interpolate function calls into a human readable string.

Reading more it seems like Radspec is a (safe) implementation of NatSpec.

I think you might have misunderstood; it's not an implementation of NatSpec, but piggybacks off of it.

[fulldecent]

Maybe

"Radspec is a safe parser for Ethereum's NatSpec"

or

"Radspec is a safe viewer for Ethereum's NatSpec".

[sohkai]

Modified to be "Radspec is a safe interpreter for Ethereum's natspec", although I'd like @onbjerg to chime in if he agrees with this :).

[onbjerg]

Radspec and Natspec are not entirely compatible, so I don't think the "slogan" should sort of say that they are

[fulldecent]

Can we make them entirely compatible and solve all the problems?

[sohkai]

@onbjerg Isn't Radspec fully compatible with Natspec (although perhaps not the other way around, in the way the interpolation happens in Radspec)?

[izqui]

From the Ethereum wiki, the natural specification (natspec) of a contract is comprised by all the special comments (@notice, @param, @dev...) that smart contract functions have and are extracted by the compiler. Technically radspec is a different language for writing Natspec dynamic expressions, but I wouldn't say it is incompatible with Natspec. The natspec dynamic expression executor had its last commit before the Ethereum mainnet was launched.

However I think we should go for a friendlier slogan, specially since a lot of developers won't know what natspec is anyway. I think it should mention that radspec produces user interface strings that can take into account call parameters out of comments in the smart contract code.

[onbjerg]

It's incompatible because Natspec is just JavaScript. Radspec is not fully compatible with JavaScript.

Also Radspec requires type annotations in some situations, Natspec never requires it.

I never thought of "Radspec is a safe alternative to Ethereum's natspec" as a slogan, just a short description/introduction 😊

[fulldecent]

Here is a rewrite that bills radspec as THE interpreter for dynamic expressions in NatSpec.

#69

I am working on the documentation for NatSpec and it will help if I can just reference the work that is being done here.

[guylando]

Why solidity documentation references radspec in the natspec documentation if they are not compatible? https://solidity.readthedocs.io/en/v0.5.8/natspec-format.html#dynamic-expressions
it is unclear if solidity supports natspec or radspec and if it supports only partial features of radspec then which ones. A lot of confusion.
Also: It is written here that natspec is unsafe: https://github.com/aragon/radspec#aside-why-is-natspec-unsafe and if radspec is a compatible extension of natspec then it would make the claim true about radspec too, so I guess that claim is equivalent to saying they are incompatible.

[fulldecent]

Here is how I documented it:

Dynamic expressions

The Solidity compiler will pass through NatSpec documentation from your Solidity source code to the JSON output as described in this guide. The consumer of this JSON output, for example the end-user client software, may present this to the end-user directly or it may apply some pre-processing.

The discussion of dynamic expressions is entirely outside the scope of Solidity. Solidity does not care what type of expressions you put in there.

---

Now this phrase is confusing:

https://github.com/aragon/radspec#aside-why-is-natspec-unsafe

Aside: Why is NatSpec unsafe? ...

This text inside Radspec is wrong. Nothing is wrong with NatSpec (as has yet been raised). Instead, there are complaints about natspec.js. Radspec should properly refer to NatSpec or natspec.js as appropriate to avoid confusion.

[guylando]

I see, another question please: How is radspec related to comments written inside solidity code? do you mean that those dynamic expressions are inserted by solidity AS IS into the metadata json and that client side software may use libraries such as radspec to interpret the dynamic expressions inside the natspec comments from the contract metadata json file?
Since contracts may be used by various tools, how will the tools that use the contract metadata file know which natspec extension was used? how will they know that radspec dynamic expressions were used and not some other library expressions? Or the dynamic expressions have a common standard for any library implementing natspec interpretation?