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 :-). Did you try digging the git history and or guile-devel historical messages that could touch that topic? -- Thanks, Maxim
