bug#10163: Incomplete/vague section of Guile Manual

[Ryan Fox <ryan@rcfox.ca>]

[-- Attachment #1: Type: text/plain, Size: 1097 bytes --]

Hello,
In section 5.7.1.4, "Writing Guile Primitives for Dia" at
http://www.gnu.org/software/guile/manual/guile.html, the description of the
square_p() implementation is incomplete. It uses a macro call to ensure
that the SCM value is a shape, but does not explain what that
implementation is:

/* Check that arg is really a shape SMOB. */
SCM_VALIDATE_SHAPE (SCM_ARG1, shape);

The explanation merely states:
"SCM_VALIDATE_SHAPE is a macro that you should define as part of your SMOB
definition: it checks that the passed parameter is of the expected type."

After some searching, I was able to figure out that the
function scm_assert_smob_type() is probably the intended behaviour for
this. However, there was no indication of this in the description.

As a side note: I'm a new Schemer, so perhaps this isn't idiomatic, but
would it make more sense to use the SCM_SMOB_PREDICATE macro instead? This
way, you can simply return false for any type, even if it isn't a shape.
Asking if a number is a shape (for example) doesn't strike me as
particularly exceptional or incorrect.

Thanks,
Ryan Fox

[-- Attachment #2: Type: text/html, Size: 1288 bytes --]