Comments
========

Needed:
1. Line comments (above or next to code lines)
2. Documentation comments (above function declarations)
3. Commented out blocks. Needs to be nestable. These really help when
   debugging, and should usually not appear in released code.

Line comments
-------------
Already implemented:

    # this is a line comment
    do_stuff()  # this is another line comment

Documentation comments
----------------------
Can simply be an ordinary comment next to the declaration it describes.

    # Does stuff.
    #
    # **Note:** Please call `prepare_stuff()` first!
    since 1.0
    func do_stuff(
        int x   # The number
    )

Placement of documentation comments:
* on the line before of the declaration
* to the right of the declaration (only for parameters and fields?)

Formatting of documentation comments:
* Could use plain markdown. It's pretty much a standard today, and more
  well-known than say Javadoc.
* A smart doc generator could parse things between apostrophes as SLUL
  code and add links if it is a reference to an identifier/type.
  It needs to suppport the following syntaxes:
    - types: `Thing`
    - identifiers: `variable`
    - functions: `function()`
    - methods: `Thing.method()`
    - constructor typeidents: `.new() -> Thing`
    - enum typeidents: `.ident -> EnumType`
    - The `-> Xxx` part should be possible to omit if it appears within
      the scope of the type or if the type is the target type.

Commented out blocks
--------------------

    #{{
    ...
    #}}

Why this syntax? It:
* Editors can find the matching { and }
* Supports nesting
* Syntax errors inside the block can be ignored

Nesting is supported because it can only appear at the start of a line,
which makes it impossible for #}} to appear inside comments or strings.
This also makes it stand out more when using inside blocks of indented code.