[pro] Looking for comments/corrections on Lisp Doc-Generation Tool Review

[Didier Verna]

Sabra Crolleton <sabra.crolleton at gmail.com> wrote:

> I put together a draft of a review of common lisp documentation
> generation tools at https://sites.google.com/site/sabraonthehill/
> lisp-document-generation-apps.

  Thank you for this feedback. I'm the author of Declt. Here are some
comments.


On the license issue:

> License info: According to the documentation, this should be able to
> be passed in the call to declt, but I could not get this to work.

One possible source of confusion is that you need to explicitely pass a
:license keyword to DECLT to get a Copying chapter (:license defaults to
nil). However, Declt will also advertise the contents of the :license
field from the ASDF system definition on the /system/ page, without
processing it. Declt doesn't try to guess the license from the ASDF
:license field because people do whatever they want in this field and it
would be too difficult to be accurate. As a result, if this field says
"GNU GPL" but you pass :LICENSE :BSD to the call to DECLT, then you will
indeed get something inconsistent.

> Properly flags the license as MIT, but makes a textual statement about
> this being under GPL3

Provided the above, that is not possible. Or, I don't understand you.

BTW, the upcoming release of Declt will support 2 new license types:
:MIT and :LGPL. Others on demand.


> Internal symbols: Only if specified in the call to the document
> generator. It does not attempt to read the asd file for this
> information

  I don't understand. Internal symbols are always documented. What has
the ASDF file to do with this ?


> Class info: Declt only provides limited information here. It only
> provides the name and the document string, unlike other packages which
> provide slots, methods, etc

  Declt does document generic functions and methods (but they do not
belong to classes). Do you mean that you would like back pointers from
classes to applicable methods ? Given multiple inheritance, that's sort
of frightening. Slots are on my TODO list.


> Slot accessors: no

  Slot accessors are generic function so they are documented as such. I
agree it would be convenient to have back pointers to them (when slots
are documented).


> I may be overly repressed, but I found inserting the name of the declt
> version "James T. Kirk" seemed a bit tacky.

  I presume you're talking about the small Declt notice that's inserted
in the final document. The next version will give you some control on
this notice by way of a :DECLT-NOTICE keyword argument (possible values:
NIL, :SHORT and :LONG).


> Installation Notes No problems other than the slight irritation of
> loading a package called com.dvlsoft.declt instead of something simple
> like declt.

  Short package names are EVIL. If that really upsets you, you can call
(com.dvlsoft.declt:nickname-package) right after loading it, and from
there on, you can use just DECLT as a nickname. You can even automate
that with CL-RCFILES for example.


> Author: Yes if defined in the call to declt
> Author Email: Yes, if defined in the call to declt
> Software Version: You need to explicitly state this in the command to declt 

  That is incorrect. All of this is extracted from the system definition
if not provided explicitly. The only thing that is not is the license
(see above).


> Conditions: no

  That's incorrect. Conditions are documented and indexed in the Data
Types section.


> Homepage: no
> Special Variable Values: No Variable names are shown, but not their
>   current values  

  [ and some other features ] I don't think those would be very useful
in a /reference/ manual (as opposed to a user manual). Maybe "what calls
what", yeah.


Otherwise, I will look into the backtraces you provided.

Thanks again.

-- 
Resistance is futile. You will be jazzimilated.

Scientific site:   http://www.lrde.epita.fr/~didier
Music (Jazz) site: http://www.didierverna.com