Requiring any stdlib module must not leak any symbols into the global namespace.

Any stdlib module may require "std.base", and use any functions from there, as well as functions from std.debug (and debug_init); but, all other modules export argument checked functions that should not be called from anywhere in stdlib -- this is the client API. If a function is needed by more than one module, move it to std.base without argument checking, and re-export with argscheck if necess- ary.

Obviously, for objects it's perfectly fine to require the file that defines the object being derived from. But to prevent accidentally calling argchecked methods, we always immediately create a prototype object with, e.g:

local Container = require "std.container" {}

(std.object is an exception to this rule because of how tightly bound to std.container it is, and does directly call some of containers methods by design).

Minimise forward declarations of functions, because having some declared as local in line, and others not is ugly and can easily cause rogue local keywords to be introduced that end up shadowing the intended declaration. Mutually recursive functions, and alternate definitions are acceptable, in which case keep the forward declarations and definitions as close together as possible to minimise any possible misunderstandings later.

Try to maintain asciibetical ordering of function definitions in each source file, except where doing so would require forward declar- ations. In that case use topological ordering to avoid the forward declarations.

Unless a table cannot possibly have a __len metamethod (i.e. it was constructed without one in the current scope), always use base.insert and base.len rather than core table.insert and the # operator, which do not honor __len in all implementations.

Unless a table cannot possibly have __pairs or __len metamethods (i.e. it was constructed without them in the current scope), always use base.pairs or base.ipairs rather than core pairs and ipairs, which do not honor __pairs or __len in all implementations.

Use consistent short names for common parameters:

fh a file handle, usually from io.open or similar fmt a format string fn a function i an index k a value, usually from pairs or similar l a list-like table n a number s a string t a table

Do argument check all object methods (functions available from an object created by a module function -- usually listed in the __index subtable of the object metatable), to catch pathological calls early, preferably using a typecheck.argscheck wrapper around the internal implementation: this way, implementation functions can call each other without excessive rechecking of argument types.

Do argument check all module functions (functions available in the table returned from requiring that module).

Do argument check metamethods, to catch pathological calls early.

LDocs should be next to each function's argcheck wrapper (if it has one) in the export table, so that it's easy to check the consistency between the types declared in the LDocs and the argument types enforced by typecheck.argscheck or equivalent.

backtick_references is disabled for stdlib, if you want an inline cross-reference, use @{reference}.

Be liberal with @see references to similar apis.

Refer to other argument names with italics (*italic* in markdown).

Try to add entries for callback function signatures, and name them with the suffix cb.

Rely on the reader to understand how : call syntax works in Lua, and don't waste effort documenting methods that are already documented as functions.

Do document the prototype chain. Don't document methods inherited from the prototype, even they have been overridden to behave consist- ently from a UI perspective even though the implementation needs to be different to provide that same UI.