Sabra Crolleton sabra.crolleton@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.

I have made changes to the declt descriptions based on Didier Verna's feedback. I will try to make corrections (or additions) to packages as swiftly as possible as I do not like to have incorrect information out in public.

Even just your thoughts on what document generation programs should and should not do would be valuable. Please let me know if you want or do not want attribution.

Thank you.

Sabra

On Mon, Sep 24, 2012 at 9:54 PM, Sabra Crolleton sabra.crolleton@gmail.comwrote:

Hello all,

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 .

As almost everyone on the list has more experience than I have with lisp (and some of you are authors of these programs), I would appreciate any corrections or comments on the draft. I've only had time to test with sbcl (1.0.58) but do intend to try to test with other lisps as well.

Thank you.

Sabra