search

aionnetwork / aion-docs

Documentation for the Aion Network.
MIT License
9 stars 8 forks source link

Contrived example used #53

Open fulldecent opened 5 years ago

fulldecent commented 5 years ago

A contrived example is used at developers/fundamentals/avm-concepts/initializable-fields/

I recommend that all examples be functional and informative. Contrived examples give the appearance that the documenter does not fully understand the value of the thing being demonstrated.

If you cannot find a real example to demonstrate the documented feature then REMOVE THE FEATURE!

Be creative! When I was writing the NatSpec documentation for Solidity, this was an excuse to go learn a little bit about botany. Software documentation exists to help our dear customers go build things that matter to them, not demonstrate our mastery of computer science concepts :-p

johnnymatthews commented 5 years ago

This issue has been added into the current sprint and will be address in the next two weeks.

johnnymatthews commented 5 years ago

A change has been submitted to address this issue: 97f53fda9ebcf3912f14a579bb9a6d0323ea8000

fulldecent commented 5 years ago

The example was updated to show somebody passing an API key through a web service.

🙅‍♂

Here is a specimen of a well-documented example code:

https://solidity.readthedocs.io/en/v0.5.11/natspec-format.html?highlight=Natspec

johnnymatthews commented 5 years ago

Looks like we don't quite understand your issue then. Please suggest an example, or even make a PR if you have the time.