Maxim Cournoyer <maxim.courno...@gmail.com> writes: > Hi Yuval, > > Yuval Langer <yuval.lan...@gmail.com> writes: > >> Hi, >> >> I am writing docstrings to guile-srfi-189 currently[1] and looking for >> good docstring style practices (that's another topic for another >> thread). >> >> I have noticed that there are some modules with Texinfo markup in >> their docstrings, but I haven't found these markups being used in any >> meaningful way. I looked up two docstrings inside the Guile manual, >> but couldn't find it there, so these docstrings are not used to >> de-duplicate documentation. The two I've searched are (srfi srfi-1)'s >> assoc and (ice-9 popen)'s open-pipe*. >> >> Someone had suggested the `guild doc-snarf` command, but it doesn't >> output any of the docstrings. What I did notice is that the text in >> the docstrings defined in the /libguile/ C files can be found in the >> Guile manual. There is a tool called `guile-snarf` for the C code >> docstrings, but that doesn't explain the Guile Scheme docstrings. >> >> I am extremely confused. Why have Texinfo in the docstrings of the >> Scheme source when the docstrings defined in the C files are used? >> Are there plans for developing tools that will display docstring in a >> more intelligent way using those markups, like in the interactive >> environment, or maybe assist in navigating the documentation? > > Sorry for not being helpful, but I've asked myself these questions > before, and would also like to know the answer. I assume there was a > plan to render some of the the Texinfo markup in the interactive > environment, but that's speculation :-).
While the built-in ,d in the REPL does not process the Texinfo, some third party tools do. For example geiser-doc-symbol-at-point. I think we should modify the ,d to support it as well. In my personal library, I wrote a script[0] to extract the documentation strings into the manual[1]. So in my experience having the Texinfo in docstrings is nice. Only gripe I have with it is that (texinfo) module is bit limited, and rejects a lot (for some value of "lot" :)) of valid texinfo. Tomas 0: https://git.wolfsden.cz/guile-wolfsden/tree/build-aux/doc-snarf.scm 1: https://files.wolfsden.cz/manuals/guile-wolfsden/guile-wolfsden-0.0.7.html#Auto_002dgenerated-documentation -- There are only two hard things in Computer Science: cache invalidation, naming things and off-by-one errors.
signature.asc
Description: PGP signature
