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
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
doctree    [Class]

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." 
  • :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]
code-prefix   doctree  [Generic function]

Returns the code-prefix of the specified doctree

section-names   doctree  [Generic function]

Returns the section-names of the specified doctree

section-prefix   doctree  [Generic function]

Returns the section-prefix of the specified doctree

+default-link-delimiters+   '(#\{ #\})  [Constant]
+default-section-prefix+   "* "  [Constant]
+default-code-prefix+   ";;; "  [Constant]
+default-section-names+   '("Arguments and Values:" "Side Effects:" "Affected By:" "Exceptional Situations:" "See Also:" "Notes:")  [Constant]
*newline*    [Variable]
doctree-tree   doctree  [Generic function]

Returns the tree that represent this doctree instance.

link-delimiters   doctree  [Generic function]

Returns as a multiple value the left and right characters that delimits a hyper link in a documentation string.

link-found-p   doctree word words  [Generic function]

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.

doc-section-p   doctree string  [Generic function]

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.

bulleted-list   doctree level  [Generic function]

Returns the bulleted list of given level.

last-list-item   doctree level  [Generic function]

Returns the last item of the bulleted list of given level.

paragraph-handle-line   doctree string &optional subtree  [Generic function]

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.

add-section   doctree section-name string &optional tree  [Generic function]

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.

add-to-paragraph   doctree string &optional subtree  [Generic function]

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.

add-to-code-block   doctree string &optional subtree  [Generic function]

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.

add-to-bulleted-list-item   doctree string  [Generic function]

Adds a string to the latest item of the latest most inner bulleted list.

add-to-bulleted-list   doctree string level  [Generic function]

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.

handle-string   doctree string  [Generic function]

Adds a string into the doctree. This method will be responsible for deciding in which subtree the given string should be added.

create-doctree-from-string   type strings &key &allow-other-keys  [Generic function]

Returns the document tree represented by the given strings when parsed with some Do What I Mean functions.

make-tree   tag  [Function]
tree-add   element tree  [Function]

Adds the specified element in the given tree.

make-item-prefix   depth  [Function]

Returns the desired list item designator according to te given depth. The depth is an integer greater than zero - aka: (integer 1 *).

trim-left-spaces   string  [Function]

Returns a substring of string, with all Tab and Space characters stripped off the beginning.

trim-prefix   prefix string &key (replace-prefix t)  [Function]

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.

starts-with   string prefix &optional ignore-left-whitespace-p  [Function]

Returns T if the designed string starts with the desired string prefix.

start-para-p   prev string  [Function]

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.

tree-tag   tree  [Function]

Returns the tag of the specified tree.

tree-p   object  [Function]

Returns T if the specified object is a doctree tree.

block-list-p   tree  [Function]

Returns T if the specified tree represent a list.

item-p   tree  [Function]

Returns T if the specified tree represent a item of a list.

paragraph-p   tree  [Function]

Returns T if the specified tree represent a paragraph.

code-block-p   tree  [Function]

Returns T if the specified tree represent a block of code.

string-bulleted-item-p   string level item-prefix-maker  [Function]

Returns T if the given string starts with the bulleted list prefix of the specified level.

close-paragraph   doctree  [Function]
split   string &optional (word-separator '(#\ #\Tab))  [Function]
with-tree-loop   (var tree) &body body  [Macro]

Iterates over tree elements. var, a symbol, will be bound at each iteration to the next element of the tree.