GRM questions

[Martin Grabmueller]

Hello list,

in the chapter about smobs in the reference manual, I have stumbled
across some sections which seem to be out of date.  Since I am not too
sure about them, I'd like to ask whether they are outdated enough the
be removed, or whether at least a note about deprecation should be
added.  Additionally, I have some general questions about smobs and
the validation macros.

* Validation macros:

  Are they stable enough and have they been agreed on, so that they
  could be documented?  I think about adding a section dealing with
  parameter validation.

* General:

  Should the section about smobs be lifted out of the data
  representation essay?  I think it deserves a chapter of its own.

  The documentation for the procedures as well as the examples use
  `long' as the type for the smob codes.  Should they be scm_bits_t
  instead?

  Is `scm_set_smob_apply' stable enough to be documented?

  The examples and description use the notion of CDR for the data slot
  of smobs.  Shouldn't that be changed to
  SCM_CELL_WORD/SCM_CELL_OBJECT?  Similar, should SCM_NEWSMOB[2/3] and
  SCM_RETURN_NEWSMOB[2/3] be documented as well?


* In node `Garbage Collecting Smobs':

     Note that, since a smob's mark bit lives in its CAR, along with the
  smob's type tag, the technique for checking the type of a smob described
  in *Note Typechecking:: will not necessarily work during GC.  If you
  need to find out whether a given object is a particular smob type
  during GC, use the following macro:

   - Macro: void SCM_GCTYP16 (SCM X)
       Return the type bits of the smob X, with the mark bit clear.

       Use this macro instead of `SCM_CAR' to check the type of a smob
       during GC.  Usually, only code called by the smob's `mark' function


* In node `Describing a New Type':

     Instead of using `scm_make_smob_type' and calling each of the
  individual `scm_set_smob_XXX' functions to register each special
  function independently, you can use `scm_make_smob_type_mfpe' to
  register all of the special functions at once as you create the smob
  type(1):

  [ Documentation for scm_make_smob_type snipped ]

Regards,
  'martin