bug#19104: eww.el vs. plist-put documentation (docstring, doc/lispref/lists.texi)

[Ivan Shmakov]

Package:  emacs
Severity: minor

        The eww.el code currently relies on plist-put modifying the
        property list given.  This mainly concerns eww-data (as of the
        recent changes), but occasionally also other variables.

        This feature is, however, undocumented.  For instance, both the
        docstring (src/fns.c) and the reference (doc/lispref/lists.texi)
        suggest an explicit (setq var (plist-put var prop val)) form
        instead, and lispref/lists.texi in particular clearly omits the
        specific conditions under which the list passed will be modified
        in-place:

    […] It may modify plist destructively, or it may construct a new
    list structure without altering the old.  […]

        Briefly scanning over eww.el, I see no actual bugs that may
        arise from that given the current plist-put implementation
        (which apparently returns a new list if and only if given nil as
        the argument, and modifies the list given otherwise.)  Still, I
        don’t feel it all that nice to rely on such an undocumented
        behavior.

        If this behavior is, however, well-known by now, I guess it
        really deserves to be documented.

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A