readme.lua: LUA to Markdown. Assumes a simple Hungarian notation.
(c) 2022 Tim Menzies <timm@ieee.org> BSD-2clause license
Usage: lua readme.lua [-h] [file1.lua file2.lua ...] > doco.md
Options:
-h --help Show help Extract doco from LUA files to Markdown. Assumes a simple Hungarian notation.
For example, this file was generated via
lua readme.lua readme.lua > README.md
I love documentation and I do not love most documentation generators.
- Why are they so complex to use?
- Why can't they be really short and easy to change?
- Why can't they just create tables for the functions, generated from in-line comments around the code?
- And if I use just a few simple naming conventions, why can't they add type hints to my favorite untyped languages (lua, lisp, etc)?
- Lines with Markdown start with
--(and we will print those). - We only show help on public function.
- Public functions are denoted with a trailing "-->", followed by
return type then some comment text. e.g.
function fred(s) --> str; Returnss, written as a string
Note the semi-colon. Do not skip it (its important). - In public function arguments, lower case versions of class type
(e.g.
data) are instances of that type (e.g.dataareDATAsodatasis a list ofDATAinstances). 5 Built in types are num, str, tab, bool, fun - User-defined types are ny word starting with two upper case leading letters is a class; e.g. DATA
- Public function arguments have the following type hints:
| What | Notes |
|---|---|
| 2 blanks | 2 blanks denote start of optional arguments |
| 4 blanks | 4 blanks denote start of local arguments |
| n | prefix for numerics |
| is | prefix for booleans |
| s | prefix for strings |
| suffix s | list of thing (so sfiles is list of strings) |
| suffix fun | suffix for functions |
| What | Notes |
|---|---|
are.of(s:str) ⇒ ?str |
top level, guesses a variable's type |
Types are either singular (one thing) or plural (a set of
things). The naming conventions for plurals is the same as
singulars, we just add an s. E.g. bools is a table of
booleans. and ns is a table of numbers.
Singulars are either bools, fun (function),
n (number), s (string), or t (table).
| What | Notes |
|---|---|
are.bool(s:str) ⇒ ?"bool" |
names starting with "is" are booleans |
are.fun(s:str) ⇒ ?"fun" |
names ending in "fun" are functions |
are.num(s:str) ⇒ ?"n" |
names start with "n" are numbers |
are.str(s:str) ⇒ ?"s" |
names starting with "s" are strings |
are.tbl(s:str) ⇒ ?"tab" |
names ending the "s" are tables |
| What | Notes |
|---|---|
hint(s1:str, type) ⇒ str |
if we know a type, add to arg (else return arg) |
pretty(s:str) ⇒ str |
clean up the signature (no spaces, no local vars) |
optional(s:str) ⇒ str |
removes local vars, returns the rest as a string |
lines(sFilename:str, fun:fun) ⇒ nil |
call fun on csv rows. |
| dump() ⇒ nil | if we have any tbl contents, print them then zap tbl |
| What | Notes |
|---|---|
main(sFiles:(str)+) ⇒ nil |
for all lines on command line, print doco to standard output |