bug#29551: 24.5; doc string of `bookmark-alist'

bug#29551: 24.5; doc string of `bookmark-alist'

[Drew Adams]

A bookmark is more than a name.

The first line of the doc string says this:

  Association list of bookmarks and their records.

That's wrong, or at best misleading.  Each entry in the alist is a
_bookmark_.  That is, each entry is a bookmark "record", whose car
is the bookmark name, and whose cdr is the associated bookmark data.

The doc should say something like this:

"Association list of bookmark names and bookmark data."
or
"Association list of bookmark records." (and then say what a record is)

In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

bug#29551: 24.5; doc string of `bookmark-alist'

[Drew Adams]

In addition, this sentence should be removed from
the doc string:

 "An entry with a key but null value means the
  entry is not used."

That's just not true.  (It might be true for the
fields used by default, but even then that fact
is unimportant.)

It is not true generally.  Anyone can program new
bookmark types, with any data whatsoever in their
records.  What the meaning/behavior of a nil field
value might be is determined only by the code that
creates and uses such a bookmark.

bug#29551: 24.5; doc string of `bookmark-alist'

[Eli Zaretskii]

> Date: Sun, 3 Dec 2017 15:41:10 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> A bookmark is more than a name.
> 
> The first line of the doc string says this:
> 
>   Association list of bookmarks and their records.
> 
> That's wrong, or at best misleading.  Each entry in the alist is a
> _bookmark_.  That is, each entry is a bookmark "record", whose car
> is the bookmark name, and whose cdr is the associated bookmark data.
> 
> The doc should say something like this:
> 
> "Association list of bookmark names and bookmark data."
> or
> "Association list of bookmark records." (and then say what a record is)

Thanks, fixed.