Represent toplevel comments in the AST

[BinderDavid]

Comments which are not doc comments are currently discarded during the lexing phase and not represented in the AST. This choice has one important downside: The comments are deleted if we perform de/-refunctionalization or use the code formatter. But toplevel comments are important in tutorials and examples, and we should guarantee that they are preserved during xfunc.

[BinderDavid]

We need some sort of syntax for this. I think we could take inspiration from GHC's use of notes: https://www.stackbuilders.com/insights/the-notes-of-ghc/ and introduce the note declaration.
Maybe something like this:

-- | foo bar
-- | baz
-- | - enumeration point 1
-- | - enumeration point 2
-- | ** something important**
note foo-bar

I.e. notes are a simple toplevel declaration note <identifier> with a doc-comment which contains the payload.

[timsueberkrueb]

We should also consider top-level doc comments for modules, e.g. prefixed //! in Rust. Could this also be subsumed by notes or would this be something separate?

[BinderDavid]

We should also consider top-level doc comments for modules, e.g. prefixed //! in Rust. Could this also be subsumed by notes or would this be something separate?

I think we can design these features together. Personally, I dislike the fact that Rust has multiple syntaxes for doc comments both before and after elements, i.e. both /// and //!, and I would like to have a consistent style where doc-comments always come first. We could start by just displaying notes in the documentation generator, and later special case a note which has the name of the module? E.g. note data::nat is special-cased? This would also allow to reference module documentation from within other doc comments.

[BinderDavid]

Or wait, if we allow name-spaced references to notes then if the module foo has a note bar then we could reference the note foo::bar. And we could have a convention that note doc contains the documentation of the module, which we would then reference with data::bool::doc or so.