scratch/hash-table-perf 681a2877cc2 35/37: Hash-table documentation updates

[Mattias Engdegård]

branch: scratch/hash-table-perf
commit 681a2877cc21db51192a894c07d4ca98629e6b12
Author: Mattias Engdegård <mattiase@acm.org>
Commit: Mattias Engdegård <mattiase@acm.org>

    Hash-table documentation updates
    
    * doc/lispref/hash.texi (Creating Hash, Other Hash):
    Manual updates for make-hash-table, hash-table-rehash-size and
    hash-table-rehash-threshold.
    * doc/lispref/objects.texi (Hash Table Type): Update example.
    * src/fns.c (Fhash_table_rehash_size, Fhash_table_rehash_threshold):
    Update doc strings.
    * etc/NEWS: Announce changes.
---
 doc/lispref/hash.texi    | 47 ++++++++---------------------------------------
 doc/lispref/objects.texi |  3 +--
 etc/NEWS                 | 15 +++++++++++++++
 lisp/emacs-lisp/comp.el  |  2 +-
 src/fns.c                | 16 ++++++++--------
 5 files changed, 33 insertions(+), 50 deletions(-)

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index 640e4f3ab0a..a226600f0bc 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -121,32 +121,10 @@ referenced in the hash table are preserved from garbage 
collection.
 @item :size @var{size}
 This specifies a hint for how many associations you plan to store in the
 hash table.  If you know the approximate number, you can make things a
-little more efficient by specifying it this way.  If you specify too
-small a size, the hash table will grow automatically when necessary, but
-doing that takes some extra time.
-
-The default size is 65.
-
-@item :rehash-size @var{rehash-size}
-When you add an association to a hash table and the table is full,
-it grows automatically.  This value specifies how to make the hash table
-larger, at that time.
-
-If @var{rehash-size} is an integer, it should be positive, and the hash
-table grows by adding approximately that much to the nominal size.  If
-@var{rehash-size} is floating point, it had better be greater
-than 1, and the hash table grows by multiplying the old size by
-approximately that number.
-
-The default value is 1.5.
-
-@item :rehash-threshold @var{threshold}
-This specifies the criterion for when the hash table is full (so
-it should be made larger).  The value, @var{threshold}, should be a
-positive floating-point number, no greater than 1.  The hash table is
-full whenever the actual number of entries exceeds the nominal size
-multiplied by an approximation to this value.  The default for
-@var{threshold} is 0.8125.
+little more efficient by specifying it this way but since the hash
+table memory is managed automatically, the gain in speed is rarely
+significant.
+
 @end table
 @end defun
 
@@ -159,7 +137,7 @@ the following specifies a hash table containing the keys
 (a symbol) and @code{300} (a number) respectively.
 
 @example
-#s(hash-table size 30 data (key1 val1 key2 300))
+#s(hash-table data (key1 val1 key2 300))
 @end example
 
 Note, however, that when using this in Emacs Lisp code, it's
@@ -172,12 +150,11 @@ The printed representation for a hash table consists of 
@samp{#s}
 followed by a list beginning with @samp{hash-table}.  The rest of the
 list should consist of zero or more property-value pairs specifying
 the hash table's properties and initial contents.  The properties and
-values are read literally.  Valid property names are @code{size},
-@code{test}, @code{weakness}, @code{rehash-size},
-@code{rehash-threshold}, and @code{data}.  The @code{data} property
+values are read literally.  Valid property names are @code{test},
+@code{weakness} and @code{data}.  The @code{data} property
 should be a list of key-value pairs for the initial contents; the
 other properties have the same meanings as the matching
-@code{make-hash-table} keywords (@code{:size}, @code{:test}, etc.),
+@code{make-hash-table} keywords (@code{:test} and @code{:weakness}),
 described above.
 
 Note that you cannot specify a hash table whose initial contents
@@ -377,14 +354,6 @@ This function returns the @var{weak} value that was 
specified for hash
 table @var{table}.
 @end defun
 
-@defun hash-table-rehash-size table
-This returns the rehash size of @var{table}.
-@end defun
-
-@defun hash-table-rehash-threshold table
-This returns the rehash threshold of @var{table}.
-@end defun
-
 @defun hash-table-size table
 This returns the current allocation size of @var{table}.  Since hash table
 allocation is managed automatically, this is rarely of interest.
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 17961ffadfa..eeabefa5603 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -1373,8 +1373,7 @@ and contents, like this:
 
 @example
 (make-hash-table)
-     @result{} #s(hash-table size 65 test eql rehash-size 1.5
-                             rehash-threshold 0.8125 data ())
+     @result{} #s(hash-table)
 @end example
 
 @noindent
diff --git a/etc/NEWS b/etc/NEWS
index f82564946b7..93e28ad6c40 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1727,6 +1727,21 @@ The former macro returns non-nil if a variable has a 
connection-local
 binding.  The latter macro returns the connection-local value of a
 variable if any, or its current value.
 
+** Hash tables
+
++++
+*** ':rehash-size' and ':rehash-threshold' args no longer have any effect.
+These keyword arguments are now ignored by 'make-hash-table'.  Emacs
+manages the memory for all hash table objects in the same way.
+The functions 'hash-table-rehash-size' and 'hash-table-rehash-threshold'
+remain for compatibility but now always return the old default values.
+
++++
+*** The printed representation has been shrunk and simplified.
+The 'test' parameter is omitted if it is 'eql' (the default), as is
+'data' if empty.  'rehash-size', 'rehash-threshold' and 'size' are
+always omitted, and ignored if present when the object is read back in.
+
 
 * Changes in Emacs 30.1 on Non-Free Operating Systems
 
diff --git a/lisp/emacs-lisp/comp.el b/lisp/emacs-lisp/comp.el
index 3b2fd25e61c..c5a3dd5f733 100644
--- a/lisp/emacs-lisp/comp.el
+++ b/lisp/emacs-lisp/comp.el
@@ -1134,7 +1134,7 @@ Return value is the fall-through block name."
 (defun comp-jump-table-optimizable (jmp-table)
   "Return t if JMP-TABLE can be optimized out."
   ;; Identify LAP sequences like:
-  ;; (byte-constant #s(hash-table size 3 test eq rehash-size 1.5 
rehash-threshold 0.8125 purecopy t data (created 126 deleted 126 changed 126)) 
. 24)
+  ;; (byte-constant #s(hash-table test eq purecopy t data (created 126 deleted 
126 changed 126)) . 24)
   ;; (byte-switch)
   ;; (TAG 126 . 10)
   (let ((targets (hash-table-values jmp-table)))
diff --git a/src/fns.c b/src/fns.c
index 7f724f2f4e7..973f3fa8ac5 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -5476,25 +5476,25 @@ DEFUN ("hash-table-count", Fhash_table_count, 
Shash_table_count, 1, 1, 0,
 
 DEFUN ("hash-table-rehash-size", Fhash_table_rehash_size,
        Shash_table_rehash_size, 1, 1, 0,
-       doc: /* Return the current rehash size of TABLE.  */)
+       doc: /* Return the rehash size of TABLE.
+This function is for compatibility only; it returns a nominal value
+without current significance.  */)
   (Lisp_Object table)
 {
   CHECK_HASH_TABLE (table);
-  /* Nominal factor by which to increase the size of a hash table.
-     No longer used; this is for compatibility.  */
-  return make_float (1.5);
+  return make_float (1.5);  /* The old default rehash-size value.  */
 }
 
 
 DEFUN ("hash-table-rehash-threshold", Fhash_table_rehash_threshold,
        Shash_table_rehash_threshold, 1, 1, 0,
-       doc: /* Return the current rehash threshold of TABLE.  */)
+       doc: /* Return the rehash threshold of TABLE.
+This function is for compatibility only; it returns a nominal value
+without current significance.  */)
   (Lisp_Object table)
 {
   CHECK_HASH_TABLE (table);
-  /* Nominal threshold for when to resize a hash table.
-     No longer used; this is for compatibility.  */
-  return make_float (0.8125);
+  return make_float (0.8125);  /* The old default rehash-threshold value.  */
 }