PSC Code Manual

util/documentation.lsp [src]

Functions for documentation build system

Functions

Function signature Description
Public
(defun-r func-sym) Registers the function FUNC-SYM points to
(doc-build) Bootstraps doc build process and opens a new blank drawing to carry it out
(doc-build-html) Builds HTML docs from files.json (generated by doc--write-json)
(docstring func-sym) Prints the full docstring of the function FUNC-SYM points to
(whatis func-sym) Prints the one-line description of the function FUNC-SYM points to
Private
(defun-r--process-command) Puts current function in user manual commands list
(defun-r--process-declare declare-form) Returns a form for inclusion in the function being processed by defun-r
(defun-r--process-declare-no-func-name _) Tells defun-r not to advise the function to advertise its name
(defun-r--process-declare-tests tests) Adds tests for defining function. Nothing is added to function body
(defun-r--process-declare-var var-spec) Processes a single form for defun-r--process-declare-vars
(defun-r--process-declare-vars vars-spec) Returns function advice that checks vars in the eval environment
(defun-r--process-declare-with-data _) Returns function advice that ensures this function was called inside a with-data call
(defun-r--process-function) Puts current function into code manual
(doc--add-docstring func-sym docstring) Adds DOCSTRING for FUNCSYM to global docstring vars
(doc--json-backend-docs) Returns the full documentation as a JSON string
(doc--json-command-docs cmd-entry) Returns documentation for a single command as a JSON string
(doc--json-file-docs file-entry) Returns file documentation as a JSON string
(doc--json-frontend-docs) Returns documentation for all commands as a JSON string
(doc--json-func-docs func-entry) Returns function documentation as a JSON string
(doc--print-docstring func-sym which) Print the docstring for FUNC-SYM from WHICH, which is either "short" or "long"
(doc--write-json) Writes file, function, and command docs to file

(defun-r func-sym)

Registers the function FUNC-SYM points to

Enables documentation generation and lookups with whatis and docstring. Replaces declare
forms in the function body. See defun-r--process-declare for declare forms.

Redefines function using defun unless *no-redefun* is non-nil.

If *dev-mode* is nil, skip most of the process: only extract docstrings and declare forms,
then redefine the function.

If *inhibit-func-name* is nil, advise the function to set a variable *func-name* with its
name as a string.

(doc-build)

Bootstraps doc build process and opens a new blank drawing to carry it out

(doc-build-html)

Builds HTML docs from files.json (generated by doc--write-json)

(docstring func-sym)

Prints the full docstring of the function FUNC-SYM points to

Returns nil if FUNC-SYM wasn't defined using the special documentation system.

VARS:
(FUNC-SYM (SYM))

(whatis func-sym)

Prints the one-line description of the function FUNC-SYM points to

Returns nil if FUNC-SYM wasn't defined using the special documentation system.

VARS:
(FUNC-SYM (SYM))

(defun-r--process-command)

Puts current function in user manual commands list

(defun-r--process-declare declare-form)

Returns a form for inclusion in the function being processed by defun-r

Each possible declare form has an expansion into a proper expression form, which is
inserted in place of the declare form in the function. Multiple declare forms are inserted
in the order specified. Declare form processors may modify the args, body, docstring, or
even name of the defining function, but should expressly declare doing so.

To define a new form, define a function named defun-r--process-declare-NAME, where NAME is
the first element of the form, e.g. defun-r--process-declare-vars is called when the form
is (vars ...). It will be called with a single arg: the cdr of the declare form. It should
return a form to be consed onto the front of the function's body. Processors may return
nil which will not be included in the function body. Put processor functions right after
this one in the file so they load as early as possible.

The entire declare form will be appended to the end of the function's docstring.

See the following for available declares:

- defun-r--process-declare-with-data
- defun-r--process-declare-vars
- defun-r--process-declare-tests

(defun-r--process-declare-no-func-name _)

Tells defun-r not to advise the function to advertise its name

(defun-r--process-declare-tests tests)

Adds tests for defining function. Nothing is added to function body

If *test-build-p* is nil, nothing happens. Otherwise, all forms are gathered together into
a test function (see defun-t) that is automatically eval'd.

This is useful in that it adds expected behavior to docstrings automatically. Tests
specified this way should be short and easy to read -- ideally the function call wrapped
in an =/equal with its expected output. Tests that require setup/teardown should be
defined using defun-t.

(defun-r--process-declare-var var-spec)

Processes a single form for defun-r--process-declare-vars

The car of VAR-SPEC is the name of the variable.

The cadr is a list of types. The type of the var must be one of the types. Specify nil for
the types list to allow any type (but still include validators). To say a var must be nil,
specify types as (nil).

If there are still elements in VAR-SPEC, they are validator forms. Each is evaluated and
if any return nil, throw an error.

(defun-r--process-declare-vars vars-spec)

Returns function advice that checks vars in the eval environment

VARS-SPEC should be a list of variable specifications for passing to
defun-r--process-declare-var.

(defun-r--process-declare-with-data _)

Returns function advice that ensures this function was called inside a with-data call

(defun-r--process-function)

Puts current function into code manual

(doc--add-docstring func-sym docstring)

Adds DOCSTRING for FUNCSYM to global docstring vars

Adds the whole DOCSTRING to *docstrings-full* and the first line only to
*docstrings-short*. Both are entered as a cons cell of the form (FUNC-SYM . DOCSTRING).

(doc--json-backend-docs)

Returns the full documentation as a JSON string

(doc--json-command-docs cmd-entry)

Returns documentation for a single command as a JSON string

(doc--json-file-docs file-entry)

Returns file documentation as a JSON string

(doc--json-frontend-docs)

Returns documentation for all commands as a JSON string

(doc--json-func-docs func-entry)

Returns function documentation as a JSON string

VARS:
(FUNC-ENTRY LIST)
(FILE-NAME STR)

(doc--print-docstring func-sym which)

Print the docstring for FUNC-SYM from WHICH, which is either "short" or "long"

Will retrieve docstring from *docstrings-short* or *docstrings-long*, respectively. If
FUNC-SYM isn't valid, return nil.

(doc--write-json)

Writes file, function, and command docs to file

All currently generated file and function documentation lives in the global variable
*file-docs*. Its contents are formatted in JSON and written to
docs/code-manual/files.json

Command documentation lives in *command-docs*. Contents are written to
docs/user-manual/commands.json