Stream: contributing

Topic: language reference

Richard Feldman (Dec 21 2025 at 18:13):

I'm starting on writing a full language reference - can anyone think of anything this list is missing?

• expressions
  • values
  • blocks
  • statements
    • assignment
    • expect
    • return
    • break (not implemented yet)
    • continue (not implemented yet)
• conditionals
  • if
  • else
    • else if
  • and
  • or
  • match
• pattern matching
  • match
    • alternatives
    • if guards on branches
  • exhaustiveness
    • catch-all patterns (underscore)
  • assignment
  • destructuring
• functions
  • pure functions
  • effectful functions
  • recursive functions
    • self-recursive functions
    • mutually recursive functions
  • tail calls
    • self-tail calls
    • tail call optimization
      • modulo cons
• naming
  • shadowing
  • constants
  • variables
  • type variables
  • type aliases
  • module names
  • as
• modules
  • type modules
  • imports
  • package modules
  • platform modules
  • application modules
• types
  • type annotations
    • where clauses
  • nominal types
    • opaque nominal types
  • structural types
  • type aliases
• static dispatch
  • methods
  • where clauses
  • aliases
• operators
  • desugaring
  • binary infix operations
    • and
    • or
    • arithmetic operators
    • comparison operators
  • unary prefix operators
    • -
    • !
  • unary postfix operators
    • ?
  • [...] (subscript operator - not implemented yet)
• collections
  • structural records
  • nominal records
  • tuples
  • structural tag unions
  • nominal tag unions
  • builtin collections
• loops
  • for
  • while
  • infinite loops

Richard Feldman (Dec 21 2025 at 18:14):

the langref assumes the reader already generally knows how to program in Roc, but is looking for a detailed explanation of how each of its parts work.

it intentionally doesn't include sections on builtin types like Str, List, etc. because those have their own documentation and it's better to have that information centralized in one place than split between the builtin docs and the language reference.

Richard Feldman (Dec 21 2025 at 18:15):

the goal is to make things highly linkable, in case there's a discussion and someone wants to point to a relevant detail about the language that someone else in the discussion might not know

Jared Ramirez (Dec 21 2025 at 18:56):

i think opaque vs transparent nominal types is missing!

Brendan Hansknecht (Dec 21 2025 at 21:22):

Looks good to me

Richard Feldman (Dec 22 2025 at 00:25):

as I'm writing this I am finding a strong urge to call it Rocipedia :grinning_face_with_smiling_eyes:

Luke Boswell (Dec 22 2025 at 01:53):

I think it should be called "The Roc Anthology" :rock_on: :guitar:

nandi (Dec 23 2025 at 07:45):

Richard Feldman said:

it intentionally doesn't include sections on builtin types like Str, List, etc. because those have their own documentation and it's better to have that information centralized in one place than split between the builtin docs and the language reference.

Where can I find the docs for those types in new compiler? I found stuff like https://github.com/roc-lang/roc/blob/13926dfdd3fe1d6d811d11984d6a692feaf60823/src/builtins/list.zig is that the docs?

Fabian Schmalzried (Dec 23 2025 at 07:51):

Currently https://github.com/roc-lang/roc/blob/main/src%2Fbuild%2Froc%2FBuiltin.roc is the best we have.

nandi (Dec 23 2025 at 08:14):

I also found stuff like https://github.com/roc-lang/roc/blob/13926dfdd3fe1d6d811d11984d6a692feaf60823/test/snapshots/repl/list_get.md

Last updated: Jan 12 2026 at 12:19 UTC