Documentation & Design Notes Review

[DyXel]

I was thinking about opening a separate issue, but they are all pretty minor and think should fit fine in just this one.

0. General: It seems code blocks line counts and actual code are ever-so-slightly misaligned, which amplifies over examples and looks bad...

2. Design note: Defaults are one way to say the same thing:
   • Says initializer its supported but compiler errors out in most cases (explicitly disabled, maybe misleading?).
   • Should probably mention that without braces ({ }) the return is also implicit.
3. Docs: From functions to local scopes, and back again
   • Same as above's design note.
4. Design note: Postfix operators: * and &
   • f: (i:int) -> * (:int) -> string = {/*...*/} doesn't actually compile. It reports a problem with the function pointer syntax.
5. Docs: Common programming concepts
   • Has (note: allowed in unsafe code only), what does this mean? I think it needs to be expanded, and maybe given a concrete example.
6. Docs: Common expressions
   • Function calls example doesn't compile: clog should be std::clog (didn't even know this was a thing), UFCS fprintf as cool as it looks would never compile, since string interpolation would return something that isn't const char*.
7. Design note: Capture
   • Postconditions are still using the old syntax.
   • String interpolation in Python should actually be f"My name is {name}" (f-strings).
8. Docs: Guaranteed initialization
   • The array example is missing the << for the std::couts, the load_from_disk function doesn't initialize buffer but x.