Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Slogan could be improved #67

Open
fulldecent opened this issue Mar 12, 2019 · 12 comments
Open

Slogan could be improved #67

fulldecent opened this issue Mar 12, 2019 · 12 comments

Comments

@fulldecent
Copy link
Contributor

"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
Copy link
Contributor

sohkai commented Mar 13, 2019

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
Copy link
Contributor Author

Maybe

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

or

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

@sohkai
Copy link
Contributor

sohkai commented Mar 19, 2019

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
Copy link
Contributor

onbjerg commented Mar 19, 2019

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

@fulldecent
Copy link
Contributor Author

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

@sohkai
Copy link
Contributor

sohkai commented Mar 19, 2019

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

@izqui
Copy link
Contributor

izqui commented Mar 21, 2019

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
Copy link
Contributor

onbjerg commented Mar 21, 2019

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
Copy link
Contributor Author

fulldecent commented Apr 4, 2019

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
Copy link

guylando commented May 19, 2019

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
Copy link
Contributor Author

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
Copy link

guylando commented May 19, 2019

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants