docs: document function/method modifiers and compiler annotations

[mbouaziz]

Adds skiplang/docs/modifiers-and-annotations.md. There was no reference for either, and the two are easy to conflate:

• A modifier is a keyword. The grammar and the type system check it, and reject what they don't understand.
• An annotation is a free-form string. The compiler never validates it — the parser takes @ plus any identifier, and every consumer does an exact string match.

That distinction has teeth. This compiles clean, with no error and no warning:

@totally_bogus_annotation
@debbug                    // typo for @debug — silently does nothing
fun helper(): Int { 42 }

which for @debug means quietly restoring CSE.

Method

Every claim is derived from the compiler source rather than from the declaration syntax, and the surprising ones were checked by compiling a program. A fact-checking pass against the source caught six real errors in my first draft — including the overridable rule and two rows of the receiver table — which are fixed here.

Notes a reader is most likely to get wrong

These are the ones worth reviewing closely:

• @debug only suppresses CSE, and is non-transitive — so a plain wrapper around a @debug call can still be merged. untracked is the transitive one, because it lives in the function's type. (This is the distinction behind Mark side-effecting stdlib native funs @debug so they aren't CSE'd #1337.)
• @may_alloc / @no_throw / @no_return are read only for bodiless functions and are silently dead otherwise. The prelude has live examples: print_string carries @no_throw and skipExit carries @no_return, both over real bodies. @may_alloc's absent-default is the unsafe direction — a native function without it is assumed to allocate nothing.
• Receiver modality: the unmodified default is not the permissive option — readonly is. frozen additionally demands a deeply frozen receiver and fails as a constraint, not at the modality check.
• Methods are final by default, but only when they have a body. Abstract members must be overridden, and marking one overridable is an error. There is no final fun — final is a constructor modifier.
• Module-level private parses but is not enforced (the check is dead code), so it's flagged as an intent marker rather than a guarantee. private at global scope is rejected.
• async type-checks but does not codegen — awaiting one fails with an ICE, and the async tests are disabled — so it's marked unusable rather than documented as if it worked.

@anything and @param are deliberately excluded: both look like annotations but are internal artifacts that cannot be written.

Also worth knowing

Unknown annotations aren't an oversight — they're the extension point. The compiler indexes functions by annotation, and #forEachFunction (@foo, ...) enumerates them. sktest's @test is exactly this and is not known to the compiler at all.

Note for reviewers

const.sk:363-364 has a comment saying @no_inline/@debug mean "don't discard calls as dead code either". That comment is stale — alwaysLive in deadcode.sk makes every call unconditionally live, so no call is ever DCE'd and @debug has nothing to do with it. The doc says CSE-only, which is correct; please don't let that comment prompt a "correction".

🤖 Generated with Claude Code

— Claude Opus 4.8 (1M context)