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

@@ -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

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"

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);