Improve documentation

[turbolent]

Various topics should be added or improved:

Tasks:

• Missing script documentation in the Cadence reference cadence-lang.org#162
• Include Examples of Multi-interface Restricted Types #2267
• Missing script documentation in the Cadence reference cadence-lang.org#162
• Update contract removal docs cadence-lang.org#163
• Documentation doesn't mention Events in contract Upgradability section #2046
• Add documentation for JSON AST #2343

Todos:

• Reference to optionals, field access + dictionary access
• "Constant means that the identifier’s association is constant, not the value itself – the value may still be changed if is mutable."
  • Make this a warning
  • Repeat this on the page describing fields
  • On the access control page, add "Remember that if you can access a let dictionary or array you can mutate its contents, this includes when they are pub or access(all) member variables of a contract, resource or struct."
• Static casting
• Add an example showing how a function can be passed to a function
• Storability
• getAccount and getAuthAccount
• Debugging: log, debugger, testing
• IDE, path from Playground
• Time-based applications
• unsafeRandom: "unsafe" meaning is two-fold:
  • Prevent accidental misuse
  • Current implementation:
    • Block ID is not a safe source, we should use the random beacon
    • Use of Go's math/rand
      • Doesn't guarantee uniformity
      • Seeded only by 64 bits
      • Not secure, e.g., based on old randoms, next ones can be predicted
• A glossary and alphabetical index of all concepts (with potential alternative names), keywords, operators, etc.
• Contract update events
• Documentation explaining script syntax in similar fashion to the Transaction documentation in Cadence section
• Clarify that adding a destructor to a resource does not "overwrite"/"replace" the destruction of the resource, it only allows additional code to be performed
• Conditions are not checked to be side-effect free yet
• Transactions are atomic. It either succeeds, and all state changes are committed, or it aborts during execution, and none of the changes are committed, even if they had been executed before the abort
• Destroying nil is a NO-OP. An optional is a single-element container, and if it has no value, there is nothing to do. Just like destroying another container, like an empty array or empty dictionary
• When loading just to destroy the value, use AnyResource/AnyStruct instead of a specific type, as it may be incorrect, in which case load will return nil
• Add missing status banners / remove unimplemented features
  • Interface Implementation Requirements: https://docs.onflow.org/cadence/language/interfaces/#interface-implementation-requirements
  • Composite Type Field Getters and Setters: https://docs.onflow.org/cadence/language/composite-types/#composite-type-field-getters-and-setters
  • Synthetic Composite Type Fields: https://docs.onflow.org/cadence/language/composite-types/#synthetic-composite-type-fields
  • Function Overloading: https://docs.onflow.org/cadence/language/functions/#function-overloading
• Subtyping for optionals, functions, etc.
• Point out which functions are unavailable for resources, e.g. Array.contains
• Paths: Re-iterate and show good + bad example for what “identifier” means
• Point out that key order is deterministic, but not defined (it is based on the hash of the key)
• log
• API documentation for built-in types and standard library types
  • Include type IDs

[rheaplex]

It may be worth explicitly noting that return values are copied.

I have an example for that here:

https://play.onflow.org/5cff15ee-7aaf-497e-af8a-1cf8b3fdc11e?type=tx&id=6018d1ce-e19a-48c8-bd3e-376565c64e22

[rheaplex]

And here's an example for the pub const gotcha:

https://play.onflow.org/3ca9083a-4662-48ec-8211-c636ac25e88d?type=account&id=0

[bluesign]

On the access control page, add "Remember that if you can access a let dictionary or array you can mutate its contents, this includes when they are pub or access(all) member variables of a contract, resource or struct."

[turbolent]

@rheaplex It's documented that it's pass-by-value, but we should make that more prominent / add it as an example / detail, agreed 👍

[turbolent]

@rheaplex also, @bluesign had the great idea to report a warning, I've opened onflow/cadence-tools#429 for that