Function document

Package:

IT.UNIMIB.DISCO.MA.CL.HELambdaP

Syntax:

  document
        FOR-WHAT
        &KEY
        DOCUMENTATION-TITLE
        FORMAT
        LAYOUT
        SOURCE
        DESTINATION
        SUPERSEDE
        ONLY-DOCUMENTED
        ONLY-EXPORTED
        EVERYTHING
        EXCLUDE-DIRECTORIES
        EXCLUDE-FILES
        SPECIAL-METHODS-DEFS-FILES
        CLEAR-DOCUMENTATION-DB
        DEBUG-LEVEL
        &ALLOW-OTHER-KEYS

    → result

Arguments and Values:

• FOR-WHAT : what to document; can be a pathname or a 'system'.
• DOCUMENTATION-TITLE : a STRING which will appear as the documentation title.
• FORMAT : a SYMBOL designating the desired kind of output.
• DESTINATION : a (directory) PATHANME where the documentation will be produced.
• ONLY-DOCUMENTED : a BOOLEAN: whether to produce documentation only for documented items.
• ONLY-EXPORTED : a BOOLEAN: whether to produce documentation only for 'exported' items.
• EVERYTHING : a BOOLEAN: whether to produce documentation for everything, no matter what.
• EXCLUDE-DIRECTORIES : a LIST of directory pathnames not to be considered.
• EXCLUDE-FILES : a list of FILES not to be considered.
• SPECIAL-METHODS-DEFS-FILES : a list of FILES to be LOADed before running the parsers.
• CLEAR-DOCUMENTATION-DB : a KEYWORD stating if and when the documentation db should be cleared.
• DEBUG-LEVEL : a number (between 0 and 42) or a string triggering more or less verbosity.

Description:

Produces the documentation for something.

The function is a wrapper for BUILD-DOCUMENTATION defaulting a few parameters, in particular the output FORMAT. The current default for FORMAT is :HTML, and experimental :HTML5 is available and it can be used to produce the documentation in HTML5 format.

The documentation, a set of HTML files and ancillary ones will be written in DESTINATION. What is saved as documentation is controlled by the arguments EVERYTHING, ONLY-DOCUMENTED and ONLY-EXPORTED. If EVERYTHING is non NIL, documentation pages for everything will be generated; otherwise non documented symbols first and non exported symbols next will be removed from the list of pages to be generated depending on the boolean values of ONLY-DOCUMENTED and ONLY-EXPORTED.

Notes:

At the time of this writing, ASDF and MK-DEFSYSTEM are supported.

The arguments SOURCE and SUPERSEDE are, at the time of this writing, effectively ignored.

The argument SPECIAL-METHODS-DEFS-FILES is a list of Common Lisp files that will be loaded before running the documentation parsers; it is assumed that these files will contain mostly DEFINE-DOCUMENTATION-EXTRACTOR and EXTRACT-NAMED-FORM-DOCUMENTATION definitions. The loading of these files is wrapped in an IGNORE-ERRORS form: failure to load one of them will not completely hamper the documentation procedure.

Note that EVERYTHING, ONLY-DOCUMENTED and ONLY-EXPORTED equal to NIL are equivalent to EVERYTHING non null.