ref: a70379d7e4b822f532fb0a8ccdd1624a90b64a68
dir: /src/docs.sl/
(defmacro (doc-for term . doc)
«Define documentation for a top level term.
If `term` is a function signature and `doc` is not specified, just
the signature will be included in the documentation, without
replacing any previously defined.
First `doc` argument is supposed to be a string with the description
of the term. The following arguments are expected to be optional tag
pairings that provide grouping for multiple symbols and "see also"
references.
Useful in cases where setting the documentation for a term can't
(or not preferred to) be made during the definition of said term.
One of those reasons is that the term is a built-in function
implemented in C.
Examples:
(doc-for (func arg (arg2 0))
"Return something about the `arg` and `arg2`. This is a short
description.
This is the longer description, following the short one.
Examples:
(func 0) → T
(func 1 3) → NIL"
:doc-group stuff
:doc-see func2)
(doc-for (func arg (:another-variant NIL)))»
:doc-group doc
(let* {[call (cons? term)]
[sym (or (and call (car term))
term)]
[callvars (and call (cdr term))]
[doc (car (separate-doc-from-body doc))]}
(if call
`(sym-set-doc ',sym ',doc ',callvars)
`(sym-set-doc ',sym ',doc))))
(defmacro (doc-group group-name doc)
"Define documentation for a group."
:doc-group doc
`(begin
(sym-set-doc (list 'doc 'group ',group-name) ,doc)))
(doc-group doc
"Writing and reading documentation.")
(doc-group prop
"Dealing with symbols' properties.")
(doc-group vm
"VM-related functions.")
(doc-for (vm-stats)
"Print various VM-related information, such as the number of GC
calls so far, heap and stack size, etc."
:doc-group vm)
(doc-group compress
"Compression.")
(doc-for (lz-pack data (level 0))
"Return data compressed using Lempel-Ziv.
The data must be an array, returned value will have the same type.
The optional `level` is between `0` and `10`. With `level` set to
`0` a simple LZSS using hashing will be performed. Levels between
`1` and `9` offer a trade-off between time/space and ratio. Level
`10` is optimal but very slow."
:doc-group compress)
(doc-for (lz-unpack data :to destination))
(doc-for (lz-unpack data :size decompressed-bytes)
"Return decompressed data previously compressed using lz-pack.
Either destination for the decompressed data or the expected size of
the decompressed data must be specified. In the latter case a new
array is allocated."
:doc-group compress)
(doc-group rand
"Random numbers generation.")
(doc-for (rand)
"Return a random non-negative fixnum on its maximum range."
:doc-group rand)
(doc-for (rand-u64)
"Return a random integer on interval [0, 2⁶⁴-1]."
:doc-group rand)
(doc-for (rand-u32)
"Return a random integer on interval [0, 2³²-1]."
:doc-group rand)
(doc-for (rand-double)
"Return a random double on interval [0.0, 1.0]."
:doc-group rand)
(doc-for (rand-float)
"Return a random float on [0.0, 1.0] interval."
:doc-group rand)
(doc-group sys
"OS-specific functions.")
(doc-for (exit (status NIL))
«Terminate the process with the specified status. Does not return.
The status is expected to be a string in case of an error.
Examples:
(exit) ; exit with status 0 (nil on Plan 9)
(exit "error") ; exit with status 1 ("error" on Plan 9)»
:doc-group sys)
(doc-group io
"I/O functionality.")
(doc-for (file path (:read NIL)
(:write NIL)
(:create NIL)
(:truncate NIL)
(:append NIL))
"Open a file for I/O.
An `io` object is returned. Without any modes specified the file
is opened in read-only mode."
:doc-group io)
(doc-for (io? term)
"Return `T` if `term` is of `io` type, `NIL` otherwise."
:doc-group io)
(doc-for (io->str io)
"Return an in-memory `io` buffer converted to a string."
:doc-group io)
(doc-for (io-eof? io)
«Return `T` if `io` is currently in the "end of file" state, `NIL`
otherwise.»
:doc-group io)
(doc-for (eof-object? term)
"Return `T` if `term` is `#<eof>`, `NIL` otherwise.
This object is returned by I/O functions to signal end of file,
where applicable."
:doc-group io)
(doc-for (buffer)
"Return an in-memory buffer for I/O, of `io` type.
A buffer can be used for both reading and writing at the same
time."
:doc-group io)
(doc-for NIL
"An empty list. Can be used as the opposite of T in boolean
expressions.
Examples:
(not NIL) → T
(if NIL 'yes 'no) → no
(car NIL) → NIL
(cdr NIL) → NIL"
:doc-see T)
(doc-for T
«A boolean "true".
Examples:
(not T) → NIL
(if T 'yes 'no) → yes»
:doc-see NIL)
(doc-group string
"String-related functionality.")
(doc-for (str . term)
«Return concatenation of terms formatted as strings.
This is equivalent to `(princ terms…)`, except the string is
returned, rather than printed.
Examples:
(str "a" 'b 1 #(0)) → "ab1#(0)"»
:doc-group string)
(doc-for (sym . term)
«Return a symbol with the name being the concatenation of terms
formatted as strings.
This is equivalent to `(sym (str terms…))`.
Examples:
(sym "a" 'b 1) → ab1»)