| Constant summary | |
|---|---|
| +default-code-prefix+ | ";;; " |
| +default-link-delimiters+ | '(#\{ #\}) |
| +default-section-names+ | '("Arguments and Values:" "Side Effects:" "Affected By:" "Exceptional Situations:" "See Also:" "Notes:") |
| +default-section-prefix+ | "* " |
| Class summary | |
|---|---|
| doctree | |
| Method summary | |
|---|---|
| add-section | doctree section-name string &optional tree |
| add-to-bulleted-list | doctree string level |
| add-to-bulleted-list-item | doctree string |
| add-to-code-block | doctree string &optional subtree |
| add-to-paragraph | doctree string &optional subtree |
| bulleted-list | doctree level |
| code-prefix | doctree |
| create-doctree-from-string | type strings &key &allow-other-keys |
| doc-section-p | doctree string |
| doctree-tree | doctree |
| handle-string | doctree string |
| last-list-item | doctree level |
| link-delimiters | doctree |
| link-found-p | doctree word words |
| paragraph-handle-line | doctree string &optional subtree |
| section-names | doctree |
| section-prefix | doctree |
| Function summary | |
|---|---|
| block-list-p | tree |
| close-paragraph | doctree |
| code-block-p | tree |
| item-p | tree |
| make-item-prefix | depth |
| make-tree | tag |
| paragraph-p | tree |
| split | string &optional (word-separator '(#\ #\Tab)) |
| start-para-p | prev string |
| starts-with | string prefix &optional ignore-left-whitespace-p |
| string-bulleted-item-p | string level item-prefix-maker |
| tree-add | element tree |
| tree-p | object |
| tree-tag | tree |
| trim-left-spaces | string |
| trim-prefix | prefix string &key (replace-prefix t) |
| Macro summary | |
|---|---|
| with-tree-loop | (var tree) &body body |
This class will be used to represent the doc string structure. Context such as paragraph and bulleted list will be repesented as vector block. This is used to retreive the context the documentation writer has indicated by its 'Do What I Mean' block.
It recognizes both indent and empty-line paragraph breaks, bulleted lists, code sample, hyper link and sections (like in the Hyperspec).
For bulleted lists the grammar can be specified using the :item-prefix-maker option of the driver. To end itemized list, just add a blank line after the last item. The depth of bulleted lists is not constrained, but if you start sub bulleted list then a blank line will end the current one and all parents at the same time. Otherwise said, like here, no other paragraph will be permitted in an item after its sub list items.
The sublists item designator will obey to the following grammar unless you have specified your own grammar (see the :item-prefix-maker option):
(- ) is the first level of list item prefix.
(-- ) is the second level of list item prefix.
(--- ) is the third level of list item prefix and so on.
Use the following options to customize the parser:
:item-prefix-maker (function): a designator for a function of one argument. Its argument will be an (integer 1 *) that represents the depth of the list. The return value is the corresponding string prefix designator for bulleted list (sublist) items of the specified depth.
:code-prefix (string): a string that designates a prefix for code snipet insertion in the documentation string. It must prefix all lines of code in the documentation string. The default value is: +default-code-prefix+ . For exemple:
(defun cludg-sample (bar)
"How to prefix code snipet in the documentation string:
;;; (setf *print-case* :downcase)
You are, of course, not limited to one line snipet."
(do-nothing))
:section-prefix (string): a string that will be used to determine if a section must be started or not if found at the beginning (ignoring left whitespaces) of the line. The default value is: +default-section-prefix+ .
:section-names (string list): a list of string indicating the section names. This must be used in conjonction with the section-prefix. For instance start a line as follows: '* See Also:'. Default value is: +default-section-names+ .
:link-delimiters (list of two character): a list of two characters that indicates the link opening and closing characters. Default value is: +default-link-delimiters+ . Link grammar: [opening-char(URL | defun | defclass | ...)closing-char]. If the hyper link can be resolved.
| :section-prefix | [Initarg] |
| :section-names | [Initarg] |
| :link-delimiters | [Initarg] |
| :code-prefix | [Initarg] |
| :item-prefix-maker | [Initarg] |
Returns as a multiple value the left and right characters that delimits a hyper link in a documentation string.
Returns T and the length (in words) if any hyper link is found. An hyper link will be found if the first character of word is equal to the specified doctree link-delimiters open-char and if any word of the (word . words) ends with the specified doctree link-delimiters closing-char.
If the doctre section prefix delimiter is a prefix of the given string then returns as a multiple value the string without section prefix delimiter, and the section name.
Returns the last item of the bulleted list of given level.
This method is typically invoked within add-to-paragraph.
It insert the given string in the doctree tree or in the subtree if given.
This the place for word recognition ; with the default implemention lisp keyword will be recognized and added within a keyword subtree block.
Insert a section of title section-name in the specified doctree-tree (or subtree if specified). Any opened paragraph will be closed before. Then if the result of trimming the section-name of string result in a non empty string then the remaining substring will be added in a newly opened paragraph.
Insert the given string in the last paragraph of the doctree tree or in the subtree if given. A paragraph will opened when needed before inserting the string. New paragraph will be opened under the following circumstances:
If the last element in the tree is not a paragraph.
If given string is empty and the previous paragraph is not empty.
If the last line of the paragraph ends with #. and has less left #Space characters than the given one.
Insert the given string, after removing its code-prefix, in the last code-block of the specified doctree (or subtree if specified). A new code-block will be opened in the doctree, or in the subtree, if the last block is not a code-block.
Adds a string to the latest item of the latest most inner bulleted list.
Adds an item to the latest most inner bulleted list of the given level. If no such level of bulleted list exists, then it will be created.
Adds a string into the doctree. This method will be responsible for deciding in which subtree the given string should be added.
Returns the document tree represented by the given strings when parsed with some Do What I Mean functions.
Returns the desired list item designator according to te given depth. The depth is an integer greater than zero - aka: (integer 1 *).
Returns a substring of string, with all Tab and Space characters stripped off the beginning.
Returns a new string that does not contain prefix anymore. Left white spaces will be ignored but kept. Prefix will be replace by as many space characters than its length if replace-prefix is T.
Returns T if the designed string starts with the desired string prefix.
Returns T if the given string correspond to the beginning of a paragraph in regards to the previous one. Otherwise said: If prev the previous one ends with #. and string the next one has more left white space than the previous one. Otherwise NIL is returned.
Returns T if the given string starts with the bulleted list prefix of the specified level.