Docs and sections

doc above a member, rootdoc above a file: shot shows them in its outlines and checks every name in backticks.

You'll learn doc and rootdoc, the three sections shot reads, and checked names.

Docs on members and files

A comment is read by nobody but you, and nobody notices when it names a function you renamed. A doc is part of the code:

--[[	The coins one player owns.	Rules: every change carries a Reason.	A purchase is an Add with a negative	amount.]]local Wallet = {}Wallet.__index = Wallet-- Adds coins and remembers whyfunction Wallet.Add(self: Wallet,	amount: number, reason: Types.Reason)

rootdoc {	The coins one player owns.	section Rules {		Every change carries a `Reason`. A		purchase is an `Add` with a negative		amount.	}	section Extend {		- a new way to earn: add its name to		  `Reason`, then call `Wallet.Add`.	}}class Wallet = {	doc { Coins the player has now }	public Balance : number	internal _history : {Entry}	...	doc { Adds coins and remembers why }	public Add(amount : number,		reason : Reason)

--[[$rootdoc
	The coins one player owns.

	Rules:
	Every change carries a `Reason`. A
	purchase is an `Add` with a negative
	amount.

	Extend:
	- a new way to earn: add its name to
	  `Reason`, then call `Wallet.Add`.
]]
local Wallet = {}
Wallet.__index = Wallet

--[[$doc
	Coins the player has now
]]
--@public Balance number
--@internal _history {Entry}

• doc { } works above fields, constructors, methods, statics, module properties and functions, and a type in Types.shot.
• One rootdoc per file. A doc { } above the declaration counts as the rootdoc, which is how you document a func.
• doc and rootdoc must start their line. Braces inside are fine as long as they pair up.

Sections

After its summary a doc can hold named sections. Three mean something to shot; any other name is kept for readers:

• section Rules: what a reader needs to use the system right without opening its files, in full sentences.
• section Extend: how to add to the system: which union to grow, which event to listen to.
• section Examples: how to call it, as code. It works on member docs too.

Where they show up

The outline also shows three docs written the same way: doc { The balance as text, like "25 coins" } above Describe, and in Types.shot, doc { Why a player's coins changed } above Reason and doc { One change to a wallet } above Entry. Add them too.

class Wallet  Wallet/Wallet.shot
-- The coins one player owns.
-- Rules:
--   Every change carries a `Reason`. A
--   purchase is an `Add` with a negative
--   amount.
-- Extend:
--   - a new way to earn: add its name to
--     `Reason`, then call `Wallet.Add`.
wallet.Balance : number  -- Coins the player has now  :20
Wallet.new(balance : number) -> Wallet  :23
wallet:Add(amount : number,
		reason : Reason)  -- Adds coins and remembers why  :31
wallet:Describe() -> string  -- The balance as text, like "25 coins"  :41
-- 1 internal member not shown (--all)

module Coins  Wallet/Coins.shot
Coins.Format(amount : number) -> string  :6
Coins.Line(entry : Entry) -> string  :10

types  Wallet/Types.shot
type Reason = "Pickup" | "Shop"  -- Why a player's coins changed  :2
type Entry = {  -- One change to a wallet  :5

Shot project .: 5 files in 2 folders

Init/
  Client.shot  client script
  Server.shot  server script
Wallet/        class Wallet   [Rules, Extend] The coins one player owns.
  Coins.shot   module Coins
  Types.shot   types          public Reason; public Entry

Next: shot outline <folder or name>, shot find <name>, shot show <Name.Member>, shot docs

Checked names

A plain name in backticks, like Wallet.Add or Reason, must still exist. With Wallet.Addd in the Extend section:

./Wallet/Wallet.shot:15:26   `Wallet.Addd` in this doc: Wallet has no Addd (renamed or removed?)
1 errors in 1 file (5 files checked, 2.2 s)