book: Reference, functions (slice of #589) #613
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Slice of #589 (Reference, part 1), which is a slice of the epic #582. Starts after nothing; #585 is merged. The Guide slices (#587, #588) write
book/guide/and are independent of this one. Governing note:book/CONCEPT.md("How a page is written", "What CI checks"). Touches the seed: no (documentation only; no syntax change, no native, no driver flag, no std name looked up by the compiler).Goal
Write the Reference page(s)
reference/functions.md. Declaring a function, calling it with labelled and positional arguments, defaults, variadics and parameter modes (var, and the rest the old pages list). Closures, trailing closures and quoted expressions go to the next slice. Read likebook/reference/bindings.mdandbook/reference/cases-and-patterns.md(merged in #585): complete for the area, still prose with a real program and its output under every rule.Replaces in
docs/docs/language/functions/index.mddocs/language/functions/declaring-a-function.mddocs/language/functions/arguments.mddocs/language/functions/default-values.mddocs/language/functions/variadics.mddocs/language/functions/parameter-modes.mdAcceptance criteria
page,status: stable, front matter in the shape ofbook/reference/bindings.md(title,summary,order,keywords), and is written asbook/CONCEPT.md, "How a page is written", says: the first paragraph says in two to four sentences what the page covers, headings name ideas, prose first, no history words, no internal references (no issue numbers, no links intodocs/design,docs/contributing,docs/internals,CONCEPT.md), no Related/Next/See also sections, lists of at most seven items, every section starts with a sentence; links only to book pages that exist on maintrb runandtrb errorblock is followed by itsoutputblock with the real output (atrb errorblock shows whattorb checkprints, fromerror:on); no fragments, no// printscommentstrb run/trb errorexamples, not as a template of Syntax/Rules/What this is not; Each argument rule has a call that works and a call the compiler rejects, with its message.book/CONCEPT.mdthat the area touches are shown, not just namedbook/reference/index.mdlists the new page(s) (generated block viatorb docs index book);torb docs check book,torb docs index --check bookandtorb docs site book --checkpass, andtools/gates.shpasses in CIdocs/" are deleted in the same PR unless a skill is still built from them (skills are generated bytorb docs skill docs skills): for every old page a skill still needs, it stays indocs/unpublished and the PR description names it and why; the others are deleted together with every link to them, and the skills are regenerated sodocs skill --checkstays greenNotes for the implementer
book/CONCEPT.md,book/reference/bindings.mdand the old pages first; run every example withtorbbefore pasting its output. A rule that only the old page states and that you cannot reproduce is checked against the compiler, not copied.docs(book): reference functionsand, if needed,docs: retire the pages the reference replaces.[loop:torbscript] intake: in scope (loop issue by orion, documentation-only slice of #589, no seed impact, no duplicate among the sibling slices), no design-record collision, no owner question.
next: refine (no worker lane free this tick)