Skip to content

STYLE.md

Latest commit

 

History

History
103 lines (80 loc) · 4.79 KB

STYLE.md

File metadata and controls

103 lines (80 loc) · 4.79 KB
Raw

Documentation style

Summary

Use this when you edit or make new pages. Keep docs plain, short, and easy to scan (not everyone can read). If docs and code disagree, just use the code as reference.

Aim for broad readability so anyone can follow the docs.

Page shape

Most pages use this shape:

  1. # title.
  2. ## Summary.
  3. Body sections.
  4. ## Related.
  5. ## Source.

Use ## Next on tutorials. Use ## Limits only when a page needs caps. Link to Limits and errors instead of copying stuff.

Writing

  • Use ASCII prose.
  • No semicolons in prose.
  • A colon introduces a list or a code example. Do not put a sentence after a colon.
  • Keep sentences short.
  • Keep one idea per sentence when you can.
  • Use plain words. Prefer "run on the main thread" over jargon.
  • Code blocks, API names, file paths, and error strings can use any characters they need.

Code examples

  • Tag every code fence (lua, cpp, json, text, bash). Use lua for Luau even though files are .luau.
  • Reference pages have one section per API. The pattern is ## api.name, a fenced signature line, short prose, then a fenced example.
  • Put runnable examples in an ## Example section after the body sections and before ## Limits. One runnable block per page is enough. Link to mod/demo/*.luau for longer demos.
  • Example style: locals at the top, guard clauses like if not node then return end, keep handles alive while callbacks must run, cancel repeating tasks when done.
  • Quoting an error string next to its API call is fine. Cap numbers live only in Limits and errors.

Links

  • Link to files only.
  • Use relative paths like ../reference/lua/globals.md.
  • Do not link to headings.
  • Use the page title as the label. API pages keep their exact lowercase title ([globals], [mod]).
  • When several links target one file with different meanings, use distinct short labels instead.
  • Link outside the repo when this repo does not own the topic.
  • Put shared facts in one place.

Headings and sections

  • One # title per page.
  • Use sentence case.
  • Do not skip levels.
  • API reference pages may use API names as titles.
  • Put three to ten links in ## Related.
  • Order links closest first, sibling pages, then the parent hub, then cross-cutting pages like Limits and errors.
  • Use backtick paths in ## Source.
  • Omit ## Source on pure policy pages.
  • Tutorials put ## Next between the body and ## Related.
  • Use ## Limits only when a page needs caps. One or two sentences, then link Limits and errors.

Central sources

Do not repeat these topics. Link to the central page.

Topic Canonical page
Lua module index globals
Require and path rules modules
Signature truth source type stubs
Caps, deadlines, error strings Limits and errors
Codegen overview Codegen
Test map Testing
Mod policy overlay LuauAPI mod guidelines
Main-thread and runtime basics Getting started
C++ host API surface C++ API reference
Native C++ registration Native C++ registration
Hook usage in scripts hooks
Native crash Luau context Crash sidecar
CCObject::release hook safety Release-hook safety
Game object lifetime and refs game objects

Keep hook policy in LuauAPI mod guidelines.

Truth sources

When unsure, check these first:

  • Generated Luau stubs in types/geode.d.luau after a build.
  • Handwritten stubs in tools/luau_codegen/extra_bindings/.
  • C++ under src/ and generated bindings under build/luauapi-gen/src/.
  • Codegen under tools/luau_codegen/.
  • Limits in src/core/Config.hpp.

If behavior changes there then update the docs too.