Overhaul spec content

[cburgdorf]

What was wrong?

• The layout of the syntax definitons is broken e.g:

• lots of broken links
• the Python indentation rules were not properly reflected in the syntax sections
• lots of missing content

How was it fixed?

Still an ongoing effort but:

1. The spec files where all split into individual files (similar to how the Rust reference is organized which makes it easier to maintain the links of each section
2. I removed the TOC preprocessor that we used for the release notes since it was causing lots of layout issues with the syntax definitons
   
3. Changed the syntax sections to properly use NEWLINE, INDENT, DEDENT tokens to describe the syntax
4. Added a bunch of new content as well as stubs for things that we will need to cover (e.g. all the expressions and statements)

[codecov-commenter]

Codecov Report

Merging #489 (c44317d) into master (7a6d874) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #489   +/-   ##
=======================================
  Coverage   87.69%   87.69%           
=======================================
  Files          80       80           
  Lines        5276     5276           
=======================================
  Hits         4627     4627           
  Misses        649      649           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7a6d874...c44317d. Read the comment docs.

[cburgdorf]

@g-r-a-n-t This is far from finished but I think it may be good to get the first chunk in before it grows to large.

[g-r-a-n-t]

Looks great. I left a bunch of comments, some of which are suggestions and others are just general thoughts that probably warrant new issues.

[g-r-a-n-t]

we could use the bin representation for bitwise ops

[g-r-a-n-t]

This might be more clear:

All types, except for Map, may be passed into and returned by functions.

[g-r-a-n-t]

All fields of struct types must be initialized.

[g-r-a-n-t]

In the future, I think there may be somewhat nuanced usage of to_mem() on values in memory.

Example:

pub fn foo(self):
  self.sum(self.my_array)
  self.sum([1, 2, 3]) # this is not copied in `sum`, as `to_mem` operates on it passively

fn sum(some_array: u8[3]):
  let sum: u256 = 0
  for val in some_array.to_mem():
    sum += val

  return sum

So I think we should remove the check requiring that the value be in storage (if it exists). This would of course be a separate issue.

[cburgdorf]

But why would we even write some_array.to_mem() here? Isn't the assumption that some_array is in memory anyway? Isn't it that we would only need to call to_mem() on something that is self.<something>? Or is this hypothetical code in which some_array may allow readonly storage pointers?

Also we might want to reconsider if to_mem can be merged with clone.

[g-r-a-n-t]

Isn't the assumption that some_array is in memory anyway?

This is the current assumption, as we require that reference type parameters be in memory.

Or is this hypothetical code in which some_array may allow readonly storage pointers?

This is what has been described in #161. to_mem would serve as a function that would guarantee that a readonly value is in memory. If the value is already in memory, then we would leave it alone, as to not incur unnecessary gas costs. If the value is in storage, then we would copy it.

[g-r-a-n-t]

Also, I'd be happy to rewrite a bunch of stuff in the data layout section after this gets merged.