snarfing docstrings in c extensions

[Samuel Barreto]

Hi everyone,

I'm trying to write a GSL wrapper in guile. I have written a lot of
simple functions using SCM_DEFINE and documented them using the last
SCM_DEFINE macro argument.

Now I'd like to make those docstrings accessible from Scheme code.
The way I do it for now is with this makefile instructions:

%.doc: %.c
/wherevere/guile/source/code/is/libguile/guile-snarf-docs -o $@ $< \
-- $(CFLAGS)

%.texi: %.doc
cat $< | guild snarf-check-and-output-texi > $@

And then call makeinfo on it.
(I had to change some hardcoded path in the guile-snarf-docs scripts so
that it worked from another directory btw.)

So I do am able to generate the info files that I want. My two problems
are:

1. how to use guile-snarf-docs portably ? (I have hardcoded them in my
Makefile for now.)
2. how to "link" them with functions defined in the extensions ? (I have
tried to (set! documentation-files "PATH/TO/doc.txt") but I think I
miss a step so that (procedure-documentation my-gsl-function) returns
the docstring I want)

And from a broader perspective, is it the way it is supposed to work ? I
mean, am I doing it the right way or are other "guile-extension-writers"
doing it otherwise ?

Thank you for your help,
samuel

[Mike Gran]

Post by Samuel Barreto
So I do am able to generate the info files that I want. My two problems
1. how to use guile-snarf-docs portably ? (I have hardcoded them in my
Makefile for now.)

Since they don't get installed, it is hard to know the most robust method.
They are used as internal tools to Guile.

Post by Samuel Barreto
...
And from a broader perspective, is it the way it is supposed to work ? I
mean, am I doing it the right way or are other "guile-extension-writers"
doing it otherwise ?

That is the way it is supposed to work. But, I stopped doing it that way.
I had the same sort of problems you are having now.

Instead, I started writing scheme wrappers around my C functions. In C,
let's say I had a library with a function named %foo. In scheme, I would
make a procedure

(define (foo x)
"docstring"
(%foo x))

It is a lot of wasted effort that way, but, it is easier to understand
for me. I'm not sure I should recommend it, tho.

-Mike Gran

[Samuel Barreto]

Post by Mike Gran

Post by Samuel Barreto
So I do am able to generate the info files that I want. My two problems
1. how to use guile-snarf-docs portably ? (I have hardcoded them in my
Makefile for now.)

Since they don't get installed, it is hard to know the most robust method.
They are used as internal tools to Guile.

Post by Samuel Barreto
...
And from a broader perspective, is it the way it is supposed to work ? I
mean, am I doing it the right way or are other "guile-extension-writers"
doing it otherwise ?

That is the way it is supposed to work. But, I stopped doing it that way.
I had the same sort of problems you are having now.
Instead, I started writing scheme wrappers around my C functions. In C,
let's say I had a library with a function named %foo. In scheme, I would
make a procedure
(define (foo x)
"docstring"
(%foo x))
It is a lot of wasted effort that way, but, it is easier to understand
for me. I'm not sure I should recommend it, tho.
-Mike Gran

Thanks for your answer, I was having the feeling that defining scheme
wrappers was the way to go. I agree that it is a lot of wasted effort,
but then a lot of boilerplate code can be written in scheme that way
(taking care of arguments validity, simpler docstrings, stuffs like
that) !

Thanks again !
sam