Suggestion: Documentation chapter

[mmontone]

I think a chapter on Lisp documentation would be good to have.

Thing like:

• docstrings
• how to get documentation of lisp stuff.
• manual generation (declt, etc).
• api documentation generation (ala javadocs)
• at least mention some of the literate programming options

[vindarel]

+ 1, good idea.

[alx-a]

I've made a pre-draft documentation.html file, named "Using and Creating Common Lisp Documentation" . https://github.com/alx-a/cl-cookbook/blob/documentation/documentation.md

Request for Comments:

1. Should a separate issue be started?

In accordance with the Cookbook spirit, I propose there should be three initial major sections:

• Quick-start recipes (such as IDE integration, ( this will have to be discussed due to copyright, there are solutions for integrating the Hyperspec into editors but I'm not sure about their legal status)
• Common Lisp Documentation Approach a beginner-friendly description, including a brief summary of the spirit and thinking behind CL documentation,
• Resources section: Summary and linkage to key resources such as The Standard Draft and *CLTL 2nd edition * and resources on documentation online.

including a presentation on ways self-documentation is implemented, as touched on by @mmontone

The key goals as I see them:

• Provide fast recipes for getting documentation integrated into learning and workflow
• Outline the existing documentation culture so that new developers understand what is out there and what kind of in-code information (and presentation) is seen as beneficial
• Link to key documents forming the existing documentation core

This is a rather protracted endeavor as there is so much history and evolution of approaches involved :). So the first section I'll draft out will be Resources with the key documents and articles involved with a summary of different approaches to digging into Common Lisp documentation.

Comments? Thanks, looking forward to discussing.

[mmontone]

Hi @alx-a,

thanks you for your contribution!

I think this is a good start. I don't consider myself great at documentation, so my feedback is going to be limited. You are probably better at writing documentation than I am.

A first comment:

• I would improve the section on Docstrings. You just point to some page where I don't immediately see how docstrings should be written. Perhaps there is not a standard for docstrings, like in Emacs Lisp for example. I would like something more in the lines of what Emacs does: https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html. But, again, perhaps there's no standard in Common Lisp and we cannot do that. But anyway, at least describe some good practices, and format docstrings in some what that they can be consumed by tools (like for example, slime-doc-contribs).

That's all I have for now.

[alx-a]

Hi Mariano, thanks for your feedback!

I completely agree. One of the CookBook sections/chapters continuously getting positive feedback, in my understanding, is iteration(loop), and this new documentation chapter can greatly benefit from more actual actionable recipies, like in that chapter.

Needs more recipes! I'll ping in a bit, when there is more.

Any comments on documentation in the REPL? Yes, IDE and all that, the power of Emacs &/Slime/Sly but I for one enjoy a nostalgic pure REPL experience every now and then.

[mmontone]

I don't have any tips on documentation at pure REPL, apart from using describe function.

For SLIME, we can mention the slime-describe-* Emacs commands (C-c C-d d by default I believe). And also perhaps mention SLIME-DOC-CONTRIBS library that improves description buffers.

Also, apropos commands, yeah. You already took those into consideration.

[alx-a]

@vindarel , I think the draft is ready for discussion. A. Shall I create a separate issue, or shall we continue here? B. Alternatively I can make a PR and mark it draft.
Please let me know.

[mmontone]

Wow. Docstrings section is very complete now. Good job!

I digress, but docstring started being very important for me, as if they are well written they are very helpful when developing interactively (not having to go to a web browser to get the documentation).

Emacs implementation is even more complete, as it integrates with Info manuals, and they are indexed. So you can go from a function name to the section in the manual they are explained.

I dream of replicating that for Common Lisp one day, but the project may be too ambitious, as it would be involve every library documentation agreeing on one documentation format (TexInfo). I started some prototypes nonetheless, with a Emacs mode that is supposed to do the same that is available for Emacs Lisp, but for Common Lisp.

TexInfo may be good enough as, unlike the usual HTML generated documentation,

• Gives direct access to the document model as it exposes an XML serialization.
• Support for definitions that appear in programming languages, like functions, variables, types, and more.
• Lots of documentation already written in Texinfo format.
• Supports indexed searches.

Ok, end of digression! Cheers.

[alx-a]

@mmontone do you have any recomendations for a library or app that can be a great example of "Emacs Style" docstrings in CL? Need to put in an example.

You bring up some very important ideas, and also they shed light on why I wrote the draft the way I did. With so much history, there are different approaches to docstrings, and at the very least it is hepful for developers to be aware of them. Hopefully it motivates developers to include a short description of how and why their docstrings are formatted the way they are.

For example, Alexandria does not target Emacs, which is appropriate, because it is a conservative CL-first library. And if someone is writing code with the goal of auto-generating documentation, them being explicit in how and why they approach docstrings a certain way is also helpful. Clarity on project documentation approach by developers may contribute to a) consistent contributions b) development of understanding of the topic, as you mention.

Thanks for the feedback!

[mmontone]

@mmontone do you have any recomendations for a library or app that can be a great example of "Emacs Style" docstrings in CL? Need to put in an example.

I think staple library docstrings are very good: https://github.com/Shinmera/staple/blob/master/documentation.lisp.

They are "generic", as they don't target any particular documentation generation tool, but at the same time are very easy to leverage from a documentation tool:

• Have a first short description line, useful for a quick description of the function, can appear in tools as Emacs mode line, or short description in generated docs.
• A long description follows after first line.
• Arguments and references to other definitions appear in uppercase.

You bring up some very important ideas, and also they shed light on why I wrote the draft the way I did. With so much history, there are different approaches to docstrings, and at the very least it is hepful for developers to be aware of them. Hopefully it motivates developers to include a short description of how and why their docstrings are formatted the way they are.

For example, Alexandria does not target Emacs, which is appropriate, because it is a conservative CL-first library.

Alexandria very much follows the format I described above. So, I'd include it as an example of good docstrings also.

[alx-a]

I think staple library docstrings are very good: https://github.com/Shinmera/staple/blob/master/documentation.lisp.

Great, will include an example along with your comments, thanks.

Alexandria very much follows the format I described above. So, I'd include it as an example of good docstrings also.

It's already in the draft, we agree :)

[vindarel]

Hello,

CLHS and REPL integration: if they require to manually copy some code, I wouldn't present the solution so upfront, but by the end. (the Cookbook first shows quick & easy solutions, not code that will rot)

Literate programming: why not, but I wouldn't list solutions, rather give an example of one that works well. Or keep it for another page and only mention it exists in a "see also" section.

Doc builders: same, we should avoid a comprehensive rotting list (but refer to the awesome-cl), and show how to include a documentation builder in an existing project. We just have to pick one that's "good enough". That's the meat of the topic I'd expect to see in a "documentation" chapter :)

thanks

[alx-a]

Hi!

• CLHS and REPL: That can be moved around, certainly. What would be the missing content/topic to start that section with?

• Literate programming : I agree, which of the listed frameworks is the favorite so I make an example? Suggestions wanted. Please name one or up to three and I'll include quick recipes.

• Add a Literate Programming separate section to the TODO list? I'm indifferent to it, but open to start a draft, after this one.

• Doc building: also need suggestions. Which one to go with? Please name one or up to three and I'll include quick recipes.

[mmontone]

For literate programming, I'd include at least these two: Erudite and QBook.

Erudite does LP in a more traditional way. I don't like that it has some rough corners in the parser. And for the output you get both the comments and code in your face all at once. I don't like that very much either, but that's how LP works in general.

QBook is simpler and less powerful regarding output markup, but can be easier to use, and is intelligent when formatting Lisp code pieces. Lisp code is interpreted and put into its own section. The result is a less contaminated output. Have a look at an example output: https://mmontone.github.io/qbook/.

If you decide to use QBook, use this fork: https://github.com/mmontone/qbook. As it has several improvements over the original.

Regarding the Cookbook, I'd put the Literate Programming in its own section/Markdown document, as it can take you quite a bit of space to explain things.