On Tuesday Jul 08 2025, Tomas Volf wrote: > Hi, > > "Dirk-Jan C. Binnema" <djcb.b...@gmail.com> writes:
>> One thing I'm not quite sure about is how to document my Guile code. >> What I want is: >> >> 1) document the code, preferable inline (i.e., emacs-style docstrings), >> so I can get documentation interactively with ",d" etc. >> 2) from that, generate some texinfo that I can can include in the info >> manual > > I can share what I am doing for my code, and you will see whether that > is helpful. :) It is, thank you! >> - seems I can use emacs-style docstrings for procedures/methods, but >> not for variables (e.g. (define foo 123) (or?) > > You can set docstrings for variables and other out-of-the-box not > supported objects, see this[0] procedure. Getting ,d working with > syntax transformers is left as an exercise for the reader. Ah, that looks very useful, thanks! At least that way I should be able to attach the docstrings to those objects. >> - moreover, I cannot generate texinfo from these docstrings (or?) > > You can get very close with the built-in tooling, all I needed was a > simple script[1] to tie it together. This whole section[2] is generated > from the source code (you will notice that not all symbols are > documented). That's quite nice, using the actual "docstrings" rather than hand-parsing ";;"-lines. Maybe something like that should be part of Guile! >> b) (ice-9 documentation) >> - it's a bit unclear if/how we can have ",d" documentation with this, >> and/or texinfo. Can it? > > I am using the docstrings, with texinfo in them[3]. It does indeed look > weird in the ,d, but geiser *does* support rendering it correctly, which > I find sufficient (since I rarely use ,d). I want to avoid writing the > same documentation twice (sans the markup), so the trade-off works for > me. > > The ,d issue *is* solvable in multiple ways, but I did not find the need > to spend time on that yet. Ah, yeah, with a little scripting it could be done. Or ,d could be pimped for this. Anyway, thank you for your suggestions, this seems useful! Kind regards, Dirk. -- Dirk-Jan C. Binnema Helsinki, Finland e:d...@djcbsoftware.nl w:www.djcbsoftware.nl gpg: 6987 9CED 1745 9375 0F14 DA98 11DD FEA9 DCC4 A036
