Table of Contents

1 Biased review of documentation tools

General Discussion
As of 24 September, 2012, Wikipedia showed 51 different non-lisp
document generators. On the same date, Cliki showed 18 lisp
documentation tools and I've found 2 more on quicklisp that were not
listed in Cliki. For some reason, I decided to compare the lisp
documentation tools and put my opinionated comments here. Several no
longer seem to be available in world. Others, I could not get to work
(either my own fault or bit rot has set in, possibly due to changes in
asdf). The last time anyone seemed to look at this issue was back in
2005: See this discussion. This,then, is my probably biased comparison
(and wish list). Comments and corrections would be greatly appreciated.

I would first note that what you would look for in a documentation
tool is going to vary, depending on what you want to do. If you are
browsing through what is loaded in quicklisp, then you want a dynamic
webserver application that allows you to quickly look at all the
different packages currently loaded. So for that you would turn to
manifest or docbrowser. If you are looking to generate an api
of the exported functions, you are going to be looking for something
simpler than if you were looking to generate a full manual for on your
own software for internal use. Hopefully this review will give you a
taste of what is available.

Unlike document generation tools in other languages, e.g. Doxygen or
Sphinx which read source code files, almost all the extant lisp document
generation progams do introspection on a running system. The only
program that I am aware of that reads the source code is cldoc.
Regardless of the approach taken, They are all intended to help with
the problem of keeping the documentation in sync with the source code.
Even if the programmer is one of those types who doesn't provide
documentation strings in the code, these applications will at least
give you the internal and external api.

The first thing that struck me in testing the packages was how
difficult this actually is. Running these tools against several
packages would trigger errors dealing with one package, warnings
against another and a third would generate documentation cleanly. I've
tried to include a sample of error messages and the packages that
generated them for all the documentation generation applications that
I could get working.

One thing I was disappointed in was how so few packages took advantage
of getting information from the asdf system. This is likely because so
few authors put the information in the asdf file. So, a plea to
all authors: please use that asd file fully. It allows for author,
maintainer, license (or licence), description and long-description.
This would help both documentation generation packages
and the entire quicklisp project. Then we can get at them
automatically rather than needing those input on the repl. E.g.

How do the lisp document generation programs compare to Doxygen or
Sphinx? So far I haven't seen the dependency visualizaions that
Doxygen can create. See examples here. In the Python world, Sphinx
seems to create a framework that you are expected to complete by
writing reStructuredText documents. Example links can be
found here. That seems like a cross between documentation-template and atdoc in the lisp world. i have not really looked hard at either Doxygen or Sphinx.

I would be remiss if I did not mention http://www.lispdoc.com/. It is
not a documentation generator, but allows you to search various Common
Lisp documents and libraries for terms or symbols.

Summary Tablealbert, document-template and hyperdoc are not part of the
Summary table below . They are, however, discussed in their own
sections below. I could not get
Albert to build. I could only get document-template to work after a
small editing change. Hyperdoc is sufficiently different that it does
not fit well into the comparison.

(6) Is there any way to tie the documentation to a testing framework
to see if every function has a test?

(7) Take text information from external files such as a text summary

(8) Shows conditions as functions in the function list. If it is a
condition, macro, generic function, there will be a flag to that
effect next to the name of the function.

(9) You can specify them in the call to the document generator or it will default to what is in the system definition.

(10) Single page with sections for constants, variables, classes,
conditions, functions and macros which can be folded.

(11) The requirement of separate pages needs to be passed to a
non-lisp program that manages the texi file. E.g.,
text2html –split node postmodern.texi

(12) Declt only provides limited information here. It only provides
the name and the document string, unlike other packages which provide
slots, methods, etc.

Wish List

Author, Maintainer, Version, License, Generation Date
It is one thing if you are just browsing through the api to use
something for your own program, but I think that the package should
show author, maintainer (possibly more valuable than the author),
version, license and generation date information if available.

Multipage Generation
Some of the packages generate a single html page. Generating a 7 MB
html page may work for some people, but personally, something that big
should be broken into manageable pieces.
Indicate wish lists: e.g. clod needs to break things out into separate
pages. Error handling needs to indicate where in the program the error
was triggered.

Class inheritance
Report class inheritance items in an appendix?

Component Dependencies
Report on the component dependencies. Yes, this duplicates looking at the asd file, but now you have it with the rest of the documentation too.

Automatic incorporation of text pages
It would be nice to allow incorporation of external text pages,
anything from the typical README or TODO or COPYING or LICENSE to more
extended introductions, and more detailed discussion of the
application. Allowing incorporation of external text pages would also allow
incorporation of use examples into the documentation.

At this point, the only package that seems to do that is
gendoc.

Document Shadowing
It would be nice to flag whenever an application has to shadow another
package it is using.

3 albert

Summary
Quicklisp does not have albert. Attempts to compile it on my systems
generate the following error on both my mac and linux systems:
:UTF-8 stream decoding error on
#<SB-SYS:FD-STREAM
the octet sequence #(248 34 10 32) cannot be decoded.

Usage

Generated Information

Author:

Author Email

License Info:

Software Version

Homepage:

Table of Contents

Index

Organization

Designate Target Directory

Multipage

Export Formats
Docbook

Show Dependencies

Generation Date

External Functions

Internal Functions

Macros

Generic Functionse

Class Info

Slot Accessors

Special Variable Values

Conditions

Package Info

General Notes

Installation Notes

Markup Language

Generate UMI

Show Uses

Show Who Uses

Statistics

What Calls What

Interfaces with Unit Testing?

Flags Missing Functions

Accept External File Input

4 atdoc

Summary
Atdoc generates documentation for Common Lisp packages. It extracts
documention strings written using a custom markup language and
generates HTML pages, TeX documents, and Info files. As a result, you
really have to use the markup language in all your document strings in
order to get full use of the package.

Note that while atdoc has an argument for
including-internal-symbols-p, I could not get it to actually generate
pages for internal symbols.

Error Items
Both Mac and Linux Boxes: When trying to generate docs for postmodern, I got the following error
message:

There is no applicable method for the generic function
#<STANDARD-GENERIC-FUNCTION SB-MOP:FINALIZE-INHERITANCE (5)>
when called with arguments
(#<BUILT-IN-CLASS REAL>).
[Condition of type SIMPLE-ERROR]

Both Mac and Linux boxes: When trying to generate docs for hunchentoot, cl-who, I got the following
error message:

5 cl-api

Summary
cl-api only generates the strings for the exported symbols. A single
page was generated for each package, with separate sections for
constants, variables, classes, functions, and macros. The html page generated allows you
to collapse each of those sections.

Error Messages:
On my both the mac and linux boxes, running cl-api against postmodern generated the
following error message:

There is no applicable method for the generic function
#<STANDARD-GENERIC-FUNCTION SB-MOP:FINALIZE-INHERITANCE (5)>
when called with arguments
(#<BUILT-IN-CLASS REAL>).
[Condition of type SIMPLE-ERROR]

Summary
Clod generates a single emacs org-mode file, which can be gigantic and
does take a substantial amount of time for org-mode in emacs to parse
and export. In fact, my test package triggered out of space errors for
some regex function in org-mode when I tried to generate a pdf version
of the documentation.

7 declt

Summary
As the cliki page states: Declt is a Texinfo reference manual
generator for ASDF systems.

Declt (Documentation Extractor from Common Lisp to Texinfo) extracts
and formats documentation from ASDF systems, including the system
itself and its components, the packages defined in the system and
definitions like constants, special variables, macros, functions,
generic functions and methods, conditions, structures and classes.

Reference manuals are generated in Texinfo format which can be
subsequently converted into info, HTML, DVI, PostScript or PDF. The
generated manuals are fully indexed and provide a complete set of
cross-references between documentation elements. For instance, files
and packages point to the definitions they provide, and those
definitions point back to package and file in which they can be found.

Because declt generates texi files, you are required to use programs
like texi2pdf or texi2html to generate other formats.

In order to generate the document format you really want. Version 1.0b14 also provides a :DECLT-NOTICE keyword argument that gives you control on the "automatically generated by Declt" notice that appears in the reference manuals.

Installation Notes
No problems.

Error Notes

I did have a couple of error messages running declt on hunchentoot and cl-postgres. Those seem to be fixed in the version 1.0b14.

Author: Yes. You can specify them in the call to the document generator or it will default to what is in the system definition.

Author Email: Yes. You can specify them in the call to the document generator or it will default to what is in the system definition.

License Info: Yes. if defined in the call to declt. Currently available types oare :BSD :GPL :MIT :LGPL. Others on demand.

Software Version: Yes

Homepage: No

Table of Contents: Yes
The main page will show the System, Modules, Files,
Packages, Definitions and Index. The actual table of contents

The system page gives the name, description, dependencies (the only
program that shows dependencies), the source directory, and the
installation directory. I don't yet see a difference between the
source directory and the installation directory.

The modules page gives the name of separate modules in the package.
Each module has its own page which lists its location and its
component files.

The files page lists the different files in the package.

Designate Target Directory: Yes

Multipage: Yes*
Note that you are passing that argument to texi2html or text2pdf
outside of lisp. For example, texi2html –split node postmodern.texi

Export Formats: Texi
You then need to run other programs to convert from texi format
to your desired format.

Show Dependencies: Yes
Declt is the only package to show dependencies. (Other packages show uses.)

Generation Date: Yes

External Functions: Yes

Internal Functions: Yes

Macros: Yes

Generic Functions: Yes

Class Info: Limited

Slot Accessors: Slot accessors are generic function so they are documented as such.

Special Variable Name and Values: Yes to Names, No to values

Conditions: Yes. They are indexed in the Data Types Section

Package Info: Yes
For example, the package info for postmodern noted both postmodern
and postmodern-system. Postmodern-system was noted as using
common-lisp and asdf. Postmodern was noted as using cl-postgres,
closer-common-lisp and s-sql.

General Notes: No

Installation Notes: No

Markup Language: No, but being worked on. Docstrings are properly escaped for texinof and some work is done to isolate paragraphs based on the presence of blank lines.

8 docbrowser

Summary
Notes: This is a dynamic webserver based package, like Manifest,
generating only dynamic html. It only shows the exported symbols.

The webpage generated for a package shows tabs for functions, classes
and variables. The functions tab lists all exported functions, It will
note whether it is a function, a generic function, or macro, but there
is no separate index for each of those types.

Generated Information
If you've seen Dr. Weitz documentation, you know what this looks like.

Author: No

Author Email: No

License Info: No
(The generated document makes reference is to a BSD style license, but
that is based on Dr. Weitz's normal packages. You must replace this
with the correct information.

Software Version: No
It generates a package version number, but you must replace this with
the correct version number.

Homepage: No
It generates a download shortcut that refers back to weitz.de, so you
must replace this with your intended webpage.

Table of Contents: Yes (Alphabetical listing of all symbols)

Index: No

Organization: Basically a dictionary of all symbols in the package

Designate Target Directory: Yes

Multipage: No

Export Formats: Single Page html

Show Dependencies: No

Show Uses: No

Show Who Uses: No

Generation Date: Yes

External Functions: Not broken out from symbol list
There is no indication of what functions are internal and what are
external. You must do this for yourself in additional editing.

Internal Functions: Not broken out from symbol list
There is no indication of what functions are internal and what are
external. You must do this for yourself in additional editing.

Macros: Partly
Macros are noted, but every symbol is in one long alphabetized list

Generic Functions: Partly
Generic functions are noted, but every symbol is in one long
alphabetized list. Generic functions names and document strings are
followed by the defined methods for that generic function and their
specified argument types.

Class Info: Partly
Symbols in the symbol list which are classes are noted as such, but it
does not indicate slots, accessors or other items connected to that class.

Slot Accessors: No
Accessors to conditions are noted, but not accessors to class slots.

Special Variable Values: No
Variables and any document string are noted, but not the values they
may have had when the documentation was generated.

Conditions: Partly
Conditions are noted, but every symbol is in one long alphabetized list.

Package Info: No

General Notes: No

Installation Notes: No

Markup Language: No
You are expected to take the finished product and actually add
additional content.

Generate UMI: No

Statistics: No

What Calls What: No

Interfaces with Unit Testing? No

Flags Missing Functions: No

Accept External File Input: No

10 gendoc

Summary
Description: This is a simple but flexible modular document generator
for Common Lisp. What I like about this one is its ability to import
other written documents, not just the document strings in the source code.

12 manifest

Summary
Manifest show the most complete set of different types of items. While
most packages satisfy themselves with exported functions, variables
and macros, Manifest provides additional information on generic
functions, slot accessors, classes, conditions, constants, used by and uses.

From the README file: Manifest is a system for semi-automatically documenting Common Lisp
packages. (A manifest tells you what's in a package. Also this system
makes manifest a bunch of information that is actually present in a
Lisp system.) The basic premise is that every exported symbol in a
package should be documented.

To check it out, after loading the system, evaluate (start) and point
your browser at the URL it returns.

Wish List

Link from each package page back to the index of packages.

Author, license, version information
Obviously, this is only to the extent possible. If the author did not
provide the information in the asd file, it will not be available.

Indexes

Usage

(ql:quickload :manifest)(manifest:START)

It will return a url with a localhost:portno. Just open your browser
to that portnumber: e.g. localhost:49434

13 qbook

Summary
Tested: Failed
Description: From the asd file: qbook generates HTML (or LaTeX)
formatted code listings of Common Lisp source files. Comments in the
source code are rendered as HTML paragraphs, text is rendered in
<pre> blocks</pre>. Headings are created by preceding the text of the
comment with one or more #\*chars.

14 tinaa

Summary
With its indexes and table of contents, Tinaa is possibly the easiest
package in terms of actually finding things from the standpoint of
different categories of items. Tinaa has the second most complete set
of different types of items (second only to Manifest). While
most packages satisfy themselves with exported functions, variables
and macros, Tinaa provides additional information on generic
functions, slot accessors, classes, conditions and uses.

As a minor item of interest, Tinaa provides a count of the number of
total symbols and number of exported symbols, but does not break those
statistics down into the specific types of symbols.

Tinaa has a separate page for each symbol, with both table of contents
and separate indexes for class, conditions, variable, function, macro, symbol,
and permuted. Tinaa can show just external symbols or external and
internal symbols.

Tinaa does not note the name of the author, the license type or the
description of the package on the index page.

15 cldoc

Summary
It appears to read the source code to pull the document strings rather
than introspecting into the system. The last revision in the version
control system seem to be in January 2006. It was not tested.

Usage
It seems to require that you pass a list of all the files to cldoc as
well as create some specific handlers for macros. See, e.g. from the
README file:

16 hyperdoc

Summary
Not tested - per the website it is not considered to be released yet.
The description of hyperdoc on the website is:

Hyperdoc is a hypertext documentation support system for Common Lisp,
licensed under a MIT-style license. Basically, it takes a symbol and
outputs a URL to that symbol's documentation.

It's supposed to be used a) by Common Lisp development environments to
provide arbitrary documentation look up on key press, and b) by
library authors to make their library's documentation conveniently
available to users of their library.