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

[Neil Jerram]

>>>>> "rm" == rm  <address@hidden> writes:

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

guile-devel, I'd say.  Although arguably you will always get the
answer yes, as the current position (I think) is that everything
exported by libguile is part of the API and therefore usable.

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

Agreed.

    rm> BTW, in case i have a documentation patch: where to send it to?
    rm> Post it here?

Strictly, address@hidden  But I don't think it would get lost if
you sent it to guile-devel instead.

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

    rm>  scm_make_vector (k, fill)

    rm> give

    rm>  scm_c_make_vector (unsigned long int k, SCM fill)

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

I may be wrong, but I don't think there's any ambiguity in the current
docs.  Wherever a type specifier is omitted, it should be understood
as SCM.  (The reason for this is a makeinfo restriction: makeinfo
can't handle a @deffn followed by a @deftypefnx.)

I think the real problem is that, in many cases, the C level function
like scm_c_make_vector isn't documented.  I completely agree that it
should be, and that its type specifiers should be shown explicitly.

Does this make sense?

        Neil