[PATCH] w3m-cookie.el: graceful entry, useless code?, documentation

[Boruch Baum <boruch_baum@xxxxxxx>]

Hi,

In starting to work on selective deletion of cookies, I began
examining the code, beginning with function `w3m-about-cookie', which
performs the rendering of the cookie management buffer.

The purposes of the attached patch is to:

1] Gracefully enter the cookie management buffer. Currently, if cookie
use is disabled, the function reports an error and creates a blank
buffer. The patch prompts the user whether to enable cookies, and
returns to the previous buffer if not.

2] Add doc-strings to some macros.

3] Remove a code snippet that doesn't seem to do anything, and the
function argument it uses. Note that this part of the patch is what
requires the second small patch file attached, which removes a
doc-string reference in `w3m-load.el' An explanation is included as an
in-line comment in the patch.

For your consideration,

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

--- w3m-cookie_orig.el	2017-06-14 04:26:41.628269575 -0400
+++ w3m-cookie.el	2017-06-14 05:47:13.865349092 -0400
@@ -89,22 +89,31 @@
 
 ;;; Cookie accessor.
 (defmacro w3m-cookie-url (cookie)
+  "Returns the url of the cookie"
   `(aref ,cookie 0))
 (defmacro w3m-cookie-domain (cookie)
+  "Returns the domain of the cookie"
   `(aref ,cookie 1))
 (defmacro w3m-cookie-secure (cookie)
+  "Returns whether the cookie is `secure'"
   `(aref ,cookie 2))
 (defmacro w3m-cookie-name (cookie)
+  "Returns the name of the cookie"
   `(aref ,cookie 3))
 (defmacro w3m-cookie-value (cookie)
+  "Returns the value of the cookie"
   `(aref ,cookie 4))
 (defmacro w3m-cookie-path (cookie)
+  "Returns the relative path of the cookie file"
   `(aref ,cookie 5))
 (defmacro w3m-cookie-version (cookie)
+  "Returns a cookie's version information"
   `(aref ,cookie 6))
 (defmacro w3m-cookie-expires (cookie)
+  "Returns when a cookie will expire"
   `(aref ,cookie 7))
 (defmacro w3m-cookie-ignore (cookie)
+  "Returns `t' if a cookie is marked to be ignored by emacs-w3m"
   `(aref ,cookie 8))
 
 (defun w3m-cookie-create (&rest args)
@@ -517,17 +526,34 @@
   (w3m-goto-url-new-session "about://cookie/" no-cache))
 
 ;;;###autoload
-(defun w3m-about-cookie (url &optional no-decode no-cache post-data &rest args)
+(defun w3m-about-cookie (url &optional no-decode no-cache &rest args)
   "Make the html contents to display and to enable you to manage cookies."
-  (unless w3m-use-cookies (error "You must enable emacs-w3m to use cookies."))
+  (unless w3m-use-cookies
+    (when
+      (y-or-n-p "Use of cookies is currently disable. Enable?")
+     (setq w3m-cookie t)))
+  (when w3m-use-cookies
   (w3m-cookie-setup)
   (let ((pos 0))
-    (when post-data
-      (dolist (pair (split-string post-data "&"))
-	(setq pair (split-string pair "="))
-	(setf (w3m-cookie-ignore
-	       (nth (string-to-number (car pair)) w3m-cookies))
-	      (eq (string-to-number (cadr pair)) 0))))
+;; BB 2017-06-14 - Useless code snippet?
+;;
+;;      1] I don't see the function ever called with the optional
+;;         arg `post-data', I don't see it documented anywhere, and
+;;         have no idea what it would do.
+;;
+;;      2] The operation performed by the snippet is to set
+;;         variables using `setf' based upon the input `post-data'.
+;;
+;;      3] But the variable names are the output of the macro
+;;        `w3m-cookie-ignore', which should only ever be `nil' or `t'!
+;;
+;;   (when post-data
+;;     (dolist (pair (split-string post-data "&"))
+;; (setq pair (split-string pair "="))
+;; (setf (w3m-cookie-ignore
+;;        (nth (string-to-number (car pair)) w3m-cookies))
+;;       (eq (string-to-number (cadr pair)) 0))))
+;; END: BB 2017-06-14 - Useless code snippet?
     (insert
      (concat
       "\
@@ -577,7 +603,7 @@
 	"</td></tr><tr><td><input type=submit value=\"OK\"></table><p>"))
       (setq pos (1+ pos)))
     (insert "</ol></form></body></html>")
-    "text/html"))
+      "text/html")))
 
 (provide 'w3m-cookie)
 

--- w3m-load_orig.el	2017-06-14 05:38:02.082815051 -0400
+++ w3m-load.el	2017-06-14 05:38:09.106777842 -0400
@@ -331,7 +331,7 @@
 (autoload 'w3m-about-cookie "w3m-cookie" "\
 Make the html contents to display and to enable you to manage cookies.
 
-\(fn URL &optional NO-DECODE NO-CACHE POST-DATA &rest ARGS)" nil nil)
+\(fn URL &optional NO-DECODE NO-CACHE &rest ARGS)" nil nil)
 
 ;;;***