ref: bbfee60f6716dce8cf7a802c044cf7d0fe8bb6f2
dir: /src/docs_extra.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."
(let* ((call (cons? term))
(sym (or (and call (car term))
term))
(callvars (and call (cdr term))))
(if call
`(sym-set-doc ',sym ',doc ',callvars)
`(sym-set-doc ',sym ',doc))))
(doc-for (vm-stats)
"Print various VM-related information, such as the number of GC
calls so far, heap and stack size, etc.")
(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-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-for (rand)
"Return a random non-negative fixnum on its maximum range.")
(doc-for (rand-u64)
"Return a random integer on interval [0, 2⁶⁴-1].")
(doc-for (rand-u32)
"Return a random integer on interval [0, 2³²-1].")
(doc-for (rand-double)
"Return a random double on interval [0.0, 1.0].")
(doc-for (rand-float)
"Return a random float on [0.0, 1.0] interval.")
(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 \"error\")")
(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-for (io? term)
"Return `T` if `term` is of `io` type, `NIL` otherwise.")
(doc-for (io->str io)
"Return an in-memory `io` buffer converted to a string.")
(doc-for (io-eof? io)
"Return `T` if `io` is currently in the \"end of file\" state, `NIL`
otherwise.")
(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-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-for NIL
"An empty list. Also used as the opposite of T.
Examples:
(not NIL) → T
(if NIL 'yes 'no) → no
(car NIL) → NIL
(cdr NIL) → NIL")
(doc-for T
"A boolean \"true\".
Examples:
(not T) → NIL
(if T 'yes 'no) → yes")
(doc-for (str . term)
"Convert terms to a concatenated string.
This is equivalent to `(princ terms…)`, except the string is
returned, rather than printed.")
(doc-for (sym . term)
"Convert terms to a symbol.
This is equivalent to `(sym (str terms…))`.")