master 519c7ca7356 19/20: Don't pretend that hash-table-size is useful

[Mattias Engdegård]

branch: master
commit 519c7ca7356fc7f9707b97c143c9495deea5b272
Author: Mattias Engdegård <mattiase@acm.org>
Commit: Mattias Engdegård <mattiase@acm.org>

    Don't pretend that hash-table-size is useful
    
    * lisp/emacs-lisp/shortdoc.el (hash-table): Remove hash-table-size entry.
    * doc/lispref/hash.texi (Other Hash):
    * src/fns.c (Fhash_table_size): Make it clear that hash-table-size is
    probably not worth using.
---
 doc/lispref/hash.texi       |  3 ++-
 lisp/emacs-lisp/shortdoc.el |  5 +----
 src/fns.c                   | 12 ++++++++----
 3 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index ff9d1799a60..aeaeab27fc0 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -386,5 +386,6 @@ This returns the rehash threshold of @var{table}.
 @end defun
 
 @defun hash-table-size table
-This returns the current nominal size of @var{table}.
+This returns the current allocation size of @var{table}.  Since hash table
+allocation is managed automatically, this is rarely of interest.
 @end defun
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 17cbf6b2d31..a6a49c72f74 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -572,10 +572,7 @@ A FUNC form can have any number of `:no-eval' (or 
`:no-value'),
    :result-string "#s(hash-table ...)")
   (hash-table-count
    :no-eval (hash-table-count table)
-   :eg-result 15)
-  (hash-table-size
-   :no-eval (hash-table-size table)
-   :eg-result 65))
+   :eg-result 15))
 
 (define-short-documentation-group list
   "Making Lists"
diff --git a/src/fns.c b/src/fns.c
index 3765fc74967..70288590e24 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -5518,10 +5518,14 @@ DEFUN ("hash-table-rehash-threshold", 
Fhash_table_rehash_threshold,
 
 
 DEFUN ("hash-table-size", Fhash_table_size, Shash_table_size, 1, 1, 0,
-       doc: /* Return the size of TABLE.
-The size can be used as an argument to `make-hash-table' to create
-a hash table than can hold as many elements as TABLE holds
-without need for resizing.  */)
+       doc: /* Return the current allocation size of TABLE.
+
+This is probably not the function that you are looking for.  To get the
+number of entries in a table, use `hash-table-count' instead.
+
+The returned value is the number of entries that TABLE can currently
+hold without growing, but since hash tables grow automatically, this
+number is rarely of interest.  */)
   (Lisp_Object table)
 {
   struct Lisp_Hash_Table *h = check_hash_table (table);