Re: scheme-only doc snarfer useful w/ (ice-9 documentation)

[Martin Grabmueller]

[ taken to guile-devel ]

> From: thi <address@hidden>
> Date: Mon, 23 Apr 2001 18:02:45 -0700
> 
> please see below for a scheme-only doc snarfer that produces output
> compatible w/ that used by `(ice-9 documentation)'.  to use, do
> something like:
> 
> $ snarf-docs *.scm > /tmp/my-docs.txt
> 
> then, make sure `find-documentation' is exported (cvs guile EOW IAGW)
> and put in your program:
> 
> (use-modules (ice-9 documentation))
> (or (member "/tmp/my-docs.txt" documentation-files)
>     (set! documentation-files (cons "/tmp/my-docs.txt"
>                                   documentation-files)))
> (write-line (find-documentation 'my-proc))
> 
> improvements and other feedback very much welcome!  (particularly, it
> would be nice to receive a patch that modifies this program to be able
> to understand stylized top-level comments -- see recent guile mailing
> lists discussions.)

Have you looked at the docstring snarfer I posted a while ago when
Neil made the first version of his docstring format suggestion?

It did snarf docstrings of the form

;; This procedure foos, or bars, depending on the argument @var{braz}.
;;-Author: Martin Grabmueller
(define (foo/bar braz)
  (if braz 'foo 'bar))

from Scheme files (where the procedure signature is determined
automatically) and docstrings of the form

/* length ls
 * Return the length of the list @var{ls}
 *-Conforms-To: r5rs
 */

from C files.

For the Scheme case, the following output is produced:

@deffn procedure foo/bar braz
This procedure foos, or bars, depending on the argument @var{braz}.
@c Author: Martin Grabmueller
@end deffn


If you want to have a look and can't find it, I can mail it to you.


Regards,
  'martin