[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

State of Docs [was] Re: Around again, and docs lead role

From: rm
Subject: State of Docs [was] Re: Around again, and docs lead role
Date: Fri, 9 May 2003 00:32:42 +0200
User-agent: Mutt/1.5.3i

On Wed, May 07, 2003 at 11:52:46PM +0100, Neil Jerram wrote:
> >>>>> "rm" == rm  <address@hidden> writes:
>     rm> I started writing up some info last night but i'm not shure
>     rm> whether the lack of documentation actually manifests some
>     rm> public vs. private API issue.
> Now, no, it just manifests lack of documentation, I'm afraid :-)
> In the future, though, I do think it would be nice to reach a
> situation where
>          documented <=> public and supported API

Yes. Right now, whenever i stumble upon a usefull but undocumented
part of the Guile API i'm somehow reluctant to use it since i fear
that it's not as stable as the documented part.
Who to consult in such a case? Guile-devel or Guile-user?

>     rm> Hmm, there a a handfull of pretty good Scheme intros
>     rm> available, why bother duplicating these efforts (better: write
>     rm> a Guile-specific addendum for one of these).
> Tricky one, but I think if we get the rest of the GUile docs right,
> and bring more users on board, the need (or not) for this will become
> clearer.

Yes, i would assume that it's up to those who write the documentation
for guile-embedding applications to provide helpfull intros/tutorials.
After all: most general Scheme tutorials will present things like
'my-fact' or 'is-prime?' while users probably want to read about
'print-in-blue' or 'image-blur' ....

>     rm> Yes. And it would be _very_ helpfull if the documentation
>     rm> would mention what modules need to be "used" for certain
>     rm> functions [(ice-9 regexp) for regular expressions ...).
> Completely agree; it's just a bug if the necessary use-module isn't
> documented.  Patches welcome!

Ok, next time i find one ...
BTW, in case i have a documentation patch: where to send it to?
Post it here?

>     rm> Another question: there's some very good information in the
>     rm> guile-workbook CVS module. But sometimes it's hard to tell
>     rm> whether a piece is documenting an existing fact of Guile or
>     rm> rather proposing a new impementation.
> IMO the starting assumption should be that workbook stuff is not
> implemented and so not valid as documentation.  If you can identify
> any text that is valid, then ideally, please convert it to a patch
> against the manual.

Finally, a proposal: I think it would be rather helpfull if the
documentation for C functions as well as CPP makros would include
the type specifier. So, instead of:

 scm_make_vector (k, fill)


 scm_c_make_vector (unsigned long int k, SCM fill)

Not having the parameter types is sometimes missleading, esp. if
the same parameter name sometimes stands for a C value and sometimes
for a SCM value (see for ex.: 'scm_vector_set_x vector k obj',  where 'k'
stands for SCM value).
I'm willing to take over that job and update the relevant parts over
the next few weeks if people find this helpfull.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]