On Fri, Apr 26, 2024 at 4:39 PM Tomas Volf <~@wolfsden.cz> wrote:
>
> On 2024-04-26 03:05:51 -0400, Nikolaos Chatzikonstantinou wrote:
> > <snip complaints about Guile's documentation extraction>
> > - `object-documentation` from `(ice-9 documentation)` only seems to
> > work with docstrings of functions, although it claims to work with
> > macros too, suggesting that the `documentation` property should be
> > set. But how? It's not explained. The info page on "Object
> > Properties" makes it seem like this suffices: (set! (documentation
> > my-function) "the docstring.") but I can't get it to work like
> > that. Docstrings cannot document files. Maybe they can document
> > macros, variables, and modules at least?
>
> What you want is:
>
> (set-object-property! foo 'documentation "Contains a @code{'bar}.")
Okay, so this can document objects. I propose that a good-enough
solution is to document symbols. This can document functions,
variables, macros, modules (although it seems that modules live in a
different namespace?) I am not sure how to document GOOP-specific
stuff, but AT LEAST we have something.
> > But the docstring format is raw, there is no markup!
>
> You can write them in whatever markup you want, I personally use texinfo
> format
> (next version of geiser will be able to process and display it nicely).
I can use any format but will there be compatibility with the tooling?
Texinfo -- fine, but there's no examples in the guile manual of such
things. It's impossible to think that the user should pick up such
ideas on their own.
You can see for example what happens under
guile/module/ice-9/streams.scm, a random file I picked from the Guile
package. Not a single procedure is docstring-documented. There's some
documentation in a giant block containing things such as
;; (stream-null? stream)
;; - yes.
(who knows what that means?) Other procedures are more fortunate,
;; (stream-map proc stream0 ...)
;; - like `map', except returns a stream of results, and not a list.
Note here the use of `' when writing `map'. I am not sure if this is
texinfo related; I don't think it is. I know it works in elisp to link
to other items. The entire block starts with
;; Use:
Is this markup? who knows. But let's look at another file, threads.scm
in the same directory. Every procedure is documented with docstrings
in texinfo format! Well, let's look at regex.scm. It uses triple
semicolons for
;;; Code:
as opposed to streams.scm's double semicolons. Why? Why not!
I don't mean to just complain. There needs to be some documentation
consistency and once established it needs to be championed, and that's
what I'm trying to accomplish...
Regards,
Nikolaos Chatzikonstantinou
