* snarfing docstrings in c extensions
@ 2018-04-07 18:59 Samuel Barreto
2018-04-08 2:27 ` Mike Gran
0 siblings, 1 reply; 3+ messages in thread
From: Samuel Barreto @ 2018-04-07 18:59 UTC (permalink / raw)
To: guile-user@gnu.org
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
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: snarfing docstrings in c extensions
2018-04-07 18:59 snarfing docstrings in c extensions Samuel Barreto
@ 2018-04-08 2:27 ` Mike Gran
2018-04-09 7:24 ` Samuel Barreto
0 siblings, 1 reply; 3+ messages in thread
From: Mike Gran @ 2018-04-08 2:27 UTC (permalink / raw)
To: Samuel Barreto; +Cc: guile-user@gnu.org
On Sat, Apr 07, 2018 at 08:59:32PM +0200, Samuel Barreto wrote:
> 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.)
Since they don't get installed, it is hard to know the most robust method.
They are used as internal tools to Guile.
> ...
> 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
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: snarfing docstrings in c extensions
2018-04-08 2:27 ` Mike Gran
@ 2018-04-09 7:24 ` Samuel Barreto
0 siblings, 0 replies; 3+ messages in thread
From: Samuel Barreto @ 2018-04-09 7:24 UTC (permalink / raw)
To: Mike Gran; +Cc: guile-user@gnu.org
> On Sat, Apr 07, 2018 at 08:59:32PM +0200, Samuel Barreto wrote:
>
>> 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.)
>
> Since they don't get installed, it is hard to know the most robust method.
> They are used as internal tools to Guile.
>
>> ...
>
>> 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
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2018-04-09 7:24 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-04-07 18:59 snarfing docstrings in c extensions Samuel Barreto
2018-04-08 2:27 ` Mike Gran
2018-04-09 7:24 ` Samuel Barreto
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).