Automatic documentation creation?

[torstenanders]

Dear developers,

 

Opusmodus has a nice and rather extensive documentation. Nevertheless, I wondered why you use manually written rtf files for that.

As you most likely know, Common Lisp already supports facilities to add documentation to symbols (e.g., functions) themselves.

Example: try (documentation 'list 'function).

 

With such facilities some automatically generated documentation could be created (at least partly), which would at least avoids certain typos. I ran in only a few typos so far in the documentation, but they exist. Here is an example: In reference, the first argument of TONALITY-SERIES is root, but that is wrong, as documentation of function itself reveals.  

 

I understand that missing formatting of the documentation strings could be a problem. However, the doc string could use a syntax like markup, which could be automatically translated into a richer formatting with headlines etc.  

 

Of course, I do not expect you to switch the documentation system now any time soon, considering all the work that went into the manual documentation. I only wonder why you did not use the existing facilities provided by Lisp itself.

 

Best,

Torsten