Re: [PATCH v2 5/9] Rename "gsmob" in Guile interface to "gdb object"

[Doug Evans <xdje42 at gmail dot com>]

Andy Wingo <wingo@igalia.com> writes:

> gdb/ChangeLog:
> 	* guile/scm-gsmob.c:
> 	* guile/lib/gdb.scm (gdb-object-kind, gdb-object-property)
> 	(set-gdb-object-property!, gdb-object-has-property?)
> 	(gadb-object-properties): Rename from gsmob-kind, gsmob-property,
> 	etc.  The fact that these are SMOBs is a C implementation detail
> 	that should not be exposed to Scheme.
>
> gdb/doc/ChangeLog:
> 	* guile.texi (GDB Scheme Data Types): Update the manual.
>
> gdb/testsuite/ChangeLog:
> 	* gdb.guile/scm-breakpoint.exp (test_bkpt_eval_funcs): Adapt to
> 	renames.

Missing entry for scm-gsmob.exp.

> [...]
> diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
> index 3f6580e..f7204e9 100644
> --- a/gdb/doc/guile.texi
> +++ b/gdb/doc/guile.texi
> @@ -331,46 +331,45 @@ This is the string passed to @code{--target} when @value{GDBN} was configured.
>  
>  @node GDB Scheme Data Types
>  @subsubsection GDB Scheme Data Types
> -@cindex gdb smobs
> +@cindex gdb objects
>  
> -@value{GDBN} uses Guile's @dfn{smob} (small object)
> -data type for all @value{GDBN} objects
> -(@pxref{Defining New Types (Smobs),,, guile, GNU Guile Reference Manual}).
> -The smobs that @value{GDBN} provides are called @dfn{gsmobs}.
> +The values exposed by @value{GDBN} to Guile are known as
> +@dfn{@value{GDBN} objects}.  There are several kinds of @value{GDBN}
> +object, and each is disjoint from all other types known to Guile.

"objects" just reads 1e6% better.
Every google search I try for "There are several kinds of foo"
uses the plural of "foo" (except where "foo" is its own plural, e.g. "fish").
If there can be no agreement on this, can we go with Eli's suggestion?
ref: https://sourceware.org/ml/gdb-patches/2014-04/msg00342.html

  @value{GDBN} objects can be of several distinct types; each type is
  different from any other type known to Guile.

> diff --git a/gdb/guile/scm-gsmob.c b/gdb/guile/scm-gsmob.c
> index 1fbd193..6d533b4 100644
> --- a/gdb/guile/scm-gsmob.c
> +++ b/gdb/guile/scm-gsmob.c
> @@ -464,23 +464,23 @@ gdbscm_clear_eqable_gsmob_ptr_slot (htab_t htab, eqable_gdb_smob *base)
>  
>  static const scheme_function gsmob_functions[] =
>  {
> -  { "gsmob-kind", 1, 0, 0, gdbscm_gsmob_kind,
> +  { "gdb-object-kind", 1, 0, 0, gdbscm_gsmob_kind,

There's a general rule of not having a "gdb" prefix on symbols provided
by the gdb module.  e.g., "execute" is named "execute" and not "gdb-execute",
"symbol?" is named "symbol?" and not "gdb-symbol?".
I'm not suggesting changing the naming.  However, I think a comment would
help a lot here explaining why "gdb-object-kind" does not actually violate
that rule.

How about something like:

  /* There's a general rule of not having a "gdb" prefix on symbols provided
     by the gdb module.  This rule is not violated here because
     "gdb-object-kind" is not intended to be read as "gdb-foo", but rather
     as "gdb-object-foo".  */