Re: Documenting Guile code

On 7/8/25 12:08 AM, Dirk-Jan C. Binnema wrote:
> 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:
>

I developed an emacs minor mode to deal with this.  It is not yet 
robust, but works
in most cases.   One writes procedure documentation as texinfo in 
comments and
then runs an emacs command that generates a formatted docstring.  It 
works by
passing the comments through `texi2any --plaintext.

ref: https://github.com/mwette/guile-contrib/blob/main/scheme-texidoc.el

It converts this:
;; @deffn {Procedure} cbase name => <ctype>
;; Given symbolic @var{name} generate a base ctype.   The name can
;; be something like @code{unsigned-int}, @code{double}, or can be a
;; @emph{cdata} machine type like @code{u64le}.  For example,
;; @example
;; (define double-type (cbase 'double))
;; @end example
;; @end deffn
(define (cbase name)
   (let* ((arch (*arch*))

to this:
;; @deffn {Procedure} cbase name => <ctype>
;; Given symbolic @var{name} generate a base ctype.   The name can
;; be something like @code{unsigned-int}, @code{double}, or can be a
;; @emph{cdata} machine type like @code{u64le}.  For example,
;; @example
;; (define double-type (cbase 'double))
;; @end example
;; @end deffn
(define (cbase name)
   "- Procedure: cbase name => <ctype>
      Given symbolic NAME generate a base ctype.  The name can be
      something like ‘unsigned-int’, ‘double’, or can be a _cdata_
      machine type like ‘u64le’.  For example,
           (define double-type (cbase 'double))"
   (let* ((arch (*arch*))