Hi, "Dirk-Jan C. Binnema" <djcb.b...@gmail.com> writes:
> Dear all, > > I'm working on a (new) guile-binding for mu[1]. I did it earlier around > ~2013 or so, it's nice to see where Guile has changed (and where not)! > > 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. :) > > I'm not quite sure if that is possible though: > > - 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. > - 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). > > If we're _not_ using docstrings but ";;-style" descriptions, > some options seem to be: > a) guild doc-snarf > - cannot find any documentation for this I *think* this is mostly intended as internal tool, hence the lack of documentation. > - seems it misunderstands some variable-defines as procedures > - do we get ,d-style documentation as well? > 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. Hope this helps, Tomas 0: https://git.wolfsden.cz/guile-wolfsden/tree/wolfsden/documentation.scm?id=541a760f76c078726f54098d7ea518e582f63a3d#n13 1: https://git.wolfsden.cz/guile-wolfsden/tree/build-aux/doc-snarf.scm?id=541a760f76c078726f54098d7ea518e582f63a3d 2: https://files.wolfsden.cz/manuals/guile-wolfsden/guile-wolfsden-0.0.7.html#Auto_002dgenerated-documentation 3: https://git.wolfsden.cz/guile-wolfsden/tree/wolfsden/fs.scm?id=541a760f76c078726f54098d7ea518e582f63a3d#n19 -- There are only two hard things in Computer Science: cache invalidation, naming things and off-by-one errors.
