* symbols.c (scm_intern_obarray_soft, scm_sysintern): Doc fixes.

* symbols.h, tags.h: Doc fixes.

libguile/symbols.c

@@ -220,6 +220,28 @@ scm_sym2ovcell (sym, obarray)
   return SCM_UNSPECIFIED;		/* not reached */
 }
 
+/* Intern a symbol whose name is the LEN characters at NAME in OBARRAY.
+
+   OBARRAY should be a vector of lists, indexed by the name's hash
+   value, modulo OBARRAY's length.  Each list has the form 
+   ((SYMBOL . VALUE) ...), where SYMBOL is a symbol, and VALUE is the
+   value associated with that symbol (in the current module?  in the
+   system module?)
+
+   To "intern" a symbol means: if OBARRAY already contains a symbol by
+   that name, return its (SYMBOL . VALUE) pair; otherwise, create a
+   new symbol, add the pair (SYMBOL . SCM_UNDEFINED) to the
+   appropriate list of the OBARRAY, and return the pair.
+
+   If softness is non-zero, don't create a symbol if it isn't already
+   in OBARRAY; instead, just return #f.
+
+   If OBARRAY is SCM_BOOL_F, create a symbol listed in no obarray and
+   return (SYMBOL . SCM_UNDEFINED).
+
+   If OBARRAY is scm_symhash, and that doesn't contain the symbol,
+   check scm_weak_symhash instead.  */
+
 #ifdef __STDC__
 SCM 
 scm_intern_obarray_soft (char *name, scm_sizet len, SCM obarray, int softness)
@@ -251,8 +273,12 @@ scm_intern_obarray_soft (name, len, obarray, softness)
 
   scm_hash = scm_strhash (tmp, i, SCM_LENGTH(obarray));
 
+  /* softness == -1 used to mean that it was known that the symbol
+     wasn't already in the obarray.  I don't think there are any
+     callers that use that case any more, but just in case...
+     -- JimB, Oct 1996  */
   if (softness == -1)
-    goto mustintern_symbol;
+    abort ();
 
  retry_new_obarray:
   for (lsym = SCM_VELTS (obarray)[scm_hash]; SCM_NIMP (lsym); lsym = SCM_CDR (lsym))
@@ -287,7 +313,6 @@ scm_intern_obarray_soft (name, len, obarray, softness)
       return SCM_BOOL_F;
     }
 
- mustintern_symbol:
   lsym = scm_makfromstr (name, len, SCM_SYMBOL_SLOTS);
 
   SCM_SETLENGTH (lsym, (long) len, scm_tc7_msymbol);
@@ -363,6 +388,8 @@ scm_intern0 (name)
 }
 
 
+/* Intern the symbol named NAME in scm_symhash, and give it the value VAL.
+   NAME is null-terminated.  */
 #ifdef __STDC__
 SCM 
 scm_sysintern (char *name, SCM val)

libguile/symbols.h

@@ -49,6 +49,31 @@
 
 extern int scm_symhash_dim;
 
+/* SCM_LENGTH(SYM) is the length of SYM's name in characters, and
+   SCM_CHARS(SYM) is the address of the first character of SYM's name.
+
+   Beyond that, there are two kinds of symbols: ssymbols and msymbols,
+   distinguished by the 'S' bit in the type.
+
+   Ssymbols are just uniquified strings.  They have a length, chars,
+   and that's it.  They use the scm_tc7_ssymbol tag (S bit clear).
+
+   Msymbols are symbols with extra slots.  These slots hold a property
+   list and a function value (for Emacs Lisp compatibility), a hash
+   code, and a flag to indicate whether their name contains multibyte
+   characters.  They use the scm_tc7_msymbol tag.
+
+   We'd like SCM_CHARS to work on msymbols just as it does on
+   ssymbols, so we'll have it point to the symbol's name as usual, and
+   store a pointer to the slots just before the name in memory.  Thus,
+   you have to do some casting and pointer arithmetic to find the
+   slots; see the SCM_SLOTS macro.
+
+   In practice, the slots always live just before the pointer to them.
+   So why not ditch the pointer, and use negative indices to refer to
+   the slots?  That's a good question; ask the author.  I think it was
+   the cognac.  */
+
 #define SCM_SYMBOLP(x) (SCM_TYP7S(x)==scm_tc7_ssymbol)
 #define SCM_LENGTH(x) (((unsigned long)SCM_CAR(x))>>8)
 #define SCM_LENGTH_MAX (0xffffffL)

libguile/tags.h

@@ -196,8 +196,13 @@ typedef long SCM;
  *
  * 101 & 111 --- tc7_ types
  *
- *		tc7_tags are 7 bit tags ending in 1x1.  These tags occur
- *		only in the CAR of heap cells.
+ *		tc7_tags are 7 bit tags ending in 1x1.  These tags
+ *		occur only in the CAR of heap cells, and have the
+ *		handy property that all bits of the CAR above the
+ *		bottom eight can be used to store a length, thus
+ *		saving a word in the body itself.  Thus, we use them
+ *		for strings, symbols, and vectors (among other
+ *		things).
  *
  *		SCM_LENGTH returns the bits in "length" (see the diagram).
  *		SCM_CHARS returns the data cast to "char *"
@@ -208,16 +213,29 @@ typedef long SCM;
  *		that applies to a particular type, see the header file
  *		for that type.
  *
+ *              Sometimes we choose the bottom seven bits carefully,
+ *              so that the 4- and 1-valued bits (called the D and S
+ *              bits) can be masked off to reveal a common type.
+ *
  *		TYP7S(X) returns TYP7, but masking out the option bit S.
  *		TYP7D(X) returns TYP7, but masking out the option bit D.
  *		TYP7SD(X) masks out both option bits.
  *
+ *              For example, all strings have 001 in the 'xxx' bits in
+ *              the diagram above, the D bit says whether it's a
+ *              substring, and the S bit says whether it's a multibyte
+ *              character string.
+ *
  *		for example:
  *						      D S
- *			scm_tc7_string    	= Gxxx0101
- *			scm_tc7_mb_string 	= Gxxx0111
- *			scm_tc7_substring	= Gxxx1101
- *			scm_tc7_mb_substring	= Gxxx1111
+ *			scm_tc7_string    	= G0010101
+ *			scm_tc7_mb_string 	= G0010111
+ *			scm_tc7_substring	= G0011101
+ *			scm_tc7_mb_substring	= G0011111
+ *
+ *		TYP7DS turns all string tags into tc7_string; thus,
+ *		testing TYP7DS against tc7_string is a quick way to
+ *		test for any kind of string.
  *
  *		TYP7S turns tc7_mb_string into tc7_string and
  *		tc7_mb_substring into tc7_substring.
@@ -225,8 +243,6 @@ typedef long SCM;
  *		TYP7D turns tc7_mb_substring into tc7_mb_string and
  *		tc7_substring into tc7_string.
  *
- *		TYP7DS turns all string tags into tc7_string.
- *
  *		Some TC7 types are subdivided into 256 subtypes giving
  *		rise to the macros:
  *
@@ -237,8 +253,7 @@ typedef long SCM;
  *		TYP16S functions similarly wrt to TYP16 as TYP7S to TYP7,
  *		but a different option bit is used (bit 2 for TYP7S,
  *		bit 8 for TYP16S).
- *
- */
+ * */