Undocumented procedures

Undocumented procedures

[Mike Gran]

Hi-

I was auditing some code to make sure I was only using 

documented procedures.  I came across a couple I've used
that aren't documented.  I can write a doc patch
but first I thought I'd check to see that they are intended
to be API.


scm_display
scm_puts
scm_new_port_table_entry
scm_sym2var

Regards,

Mike Gran

Re: Undocumented procedures

[rixed]

> I came across a couple I've used that aren't documented.
> (...)
> 
> scm_display
> scm_puts

These two are "documented" in the sense that they are used in the
manual, more precisely in chapter about smob for the print_image()
sample function.
So they are mean to be public I guess.

Re: Undocumented procedures

[Ludovic Courtès]

Hi!

And happy new year!  :-)

Mike Gran <spk121@yahoo.com> skribis:

> scm_display

A matter of adding it as a @deffnx below ‘display’ under “Scheme Write”.

> scm_puts

This and scm_putc should be documented, yes.

> scm_new_port_table_entry

Actually the whole port subsystem is undocumented.  :-(  So yes, would
be great to document.

> scm_sym2var

It’s public for historical reason, but I personally don’t like it,
because it has a stupid name and complex semantics.  ;-)

Depending on what you’re doing, you may be able to use one of the scm_c_
functions in modules.h.  WDYT?

Anyway, patches appreciated on the doc front!

Thanks,
Ludo’.

Re: Undocumented procedures

[Mike Gran]

> From: Ludovic Courtès <ludo@gnu.org>
 >>  scm_display
> 
> A matter of adding it as a @deffnx below ‘display’ under “Scheme Write”.
> 
>>  scm_puts
> 
> This and scm_putc should be documented, yes.
> 
>>  scm_new_port_table_entry
> 
> Actually the whole port subsystem is undocumented.  :-(  So yes, would
> be great to document.

OK.  I'll try to come up with a patch for the above 3.
 
> 
>>  scm_sym2var
> 
> It’s public for historical reason, but I personally don’t like it,
> because it has a stupid name and complex semantics.  ;-)
 
> 
> Depending on what you’re doing, you may be able to use one of the scm_c_
> functions in modules.h.  WDYT?

It always bothered me, though, that the many scm_c_lookup and
scm_c_{public,private}_* procedures have so many non-local exits.
It does seem like a lot of C code is necessary just to check if a
variable is there or not, since you have to catch all the exceptions.
 
> 
> Anyway, patches appreciated on the doc front!
 
I'll see what I can do.

Re: Undocumented procedures

[Andy Wingo]

On Tue 03 Jan 2012 23:28, Mike Gran <spk121@yahoo.com> writes:

>> From: Ludovic Courtès <ludo@gnu.org>
>>>  scm_sym2var
>> 
>> It’s public for historical reason, but I personally don’t like it,
>> because it has a stupid name and complex semantics.  ;-)
>  
>> 
>> Depending on what you’re doing, you may be able to use one of the scm_c_
>> functions in modules.h.  WDYT?
>
> It always bothered me, though, that the many scm_c_lookup and
> scm_c_{public,private}_* procedures have so many non-local exits.
> It does seem like a lot of C code is necessary just to check if a
> variable is there or not, since you have to catch all the exceptions.

What about scm_c_public_variable ?  Granted, it will exit nonlocally if
the module doesn't exist and have a public interface, but it does return
#f if the name is not bound in the given module.

Andy
-- 
http://wingolog.org/

Re: Undocumented procedures

[Andy Wingo]

On Mon 02 Jan 2012 04:04, Mike Gran <spk121@yahoo.com> writes:

> scm_new_port_table_entry

As Ludo says, the port implementation is terrible underdocumented.  But,
this function isn't really so great.  It is what is available in 2.0,
but in 2.2 there are a couple of versions that work better:
scm_c_make_port, and scm_c_make_port_with_encoding.  We can probably
backport one or both to stable-2.0 if that's the thing to do, dunno.

So do look at the code in `master' before doing any serious
documentation for ports.

Cheers,

Andy
-- 
http://wingolog.org/