Re: Fixing session management for individual buffers [PATCH]

[Boruch Baum <boruch_baum@xxxxxxx>]

On 2018-02-16 15:54, Katsumi Yamaoka wrote:
> I've installed your patch as is (before trying the new features).
> Thank you.
>
> But please consider Emacs' convention about doc string:
> (info "elisp(Documentation Tips)") <- type `C-x C-e' here.
> ,----
> | • The first line of the documentation string should consist of one or
> |   two complete sentences that stand on their own as a summary.  ‘M-x
> |   apropos’ displays just the first line, and if that line’s contents
> |   don’t stand on their own, the result looks bad.
> `----

Fixed here. Apologies again.

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

Index: ChangeLog
===================================================================
RCS file: /storage/cvsroot/emacs-w3m/ChangeLog,v
retrieving revision 1.3648
diff -u -r1.3648 ChangeLog
--- ChangeLog	16 Feb 2018 06:53:15 -0000	1.3648
+++ ChangeLog	16 Feb 2018 10:38:51 -0000
@@ -1,3 +1,8 @@
+2018-02-16  Boruch Baum  <boruch_baum@xxxxxxx>
+
+	* w3m-session.el: Reformat docstrings for proper opening summary
+	sentence.
+
 2018-02-16  Katsumi Yamaoka  <yamaoka@xxxxxxx>
 
 	* w3m-fb.el (w3m-fb-mode, w3m-fb-delete-frame-kill-buffers):
Index: w3m-session.el
===================================================================
RCS file: /storage/cvsroot/emacs-w3m/w3m-session.el,v
retrieving revision 1.42
diff -u -r1.42 w3m-session.el
--- w3m-session.el	16 Feb 2018 06:53:15 -0000	1.42
+++ w3m-session.el	16 Feb 2018 10:38:51 -0000
@@ -104,14 +104,16 @@
   (autoload 'w3m-save-list "w3m"))
 
 (defvar w3m-session-group-open nil
-  "If a session-group is currently open, ie. when displaying a
-  list of buffers for an individual session, this should be set
-  to the session (session-group) number.
-
-  There is a legacy terminology problem that needs to be addressed
-  here. The documentation and symbol names currently confuse
-  'sessions', 'buffers`, and 'session-groups'. A 'session-group'
-  is identical to a 'session' that has more than one 'buffer'.")
+  "Which session-group is open.
+
+If a session-group is currently open, ie. when displaying a
+list of buffers for an individual session, this should be set
+to the session (session-group) number.
+
+There is a legacy terminology problem that needs to be addressed
+here. The documentation and symbol names currently confuse
+'sessions', 'buffers`, and 'session-groups'. A 'session-group'
+is identical to a 'session' that has more than one 'buffer'.")
 
 (defcustom w3m-session-file
   (expand-file-name ".sessions" w3m-profile-directory)
@@ -810,10 +812,12 @@
     (message "Session goto(%s)...done" title)))
 
 (defun w3m-session-rename (sessions num)
-  ; When num is a cons cell, we are not dealing with a session, but
-  ; with a single buffer entry (ie. a tab) within a session. The car
-  ; of the cons will be the session number, and the cdr will be the
-  ; buffer number.
+  "Rename an entry (either a session or a buffer).
+
+Rename session number NUM, when NUM is an integer. NUM may also
+be a cons cell, for which the car is a session number and the cdr
+is a buffer entry (ie. a tab) within that session. In that case
+rename the buffer entry."
   (let* ((default-prompt "Enter new session title (C-g to abort): ")
          (prompt default-prompt)
          overwrite
@@ -864,10 +868,14 @@
     (w3m-save-list w3m-session-file sessions)))
 
 (defun w3m-session-delete (sessions num)
+  "Delete an entry (either a session or a buffer).
+
+Delete session number NUM, when NUM is an integer. NUM may also
+be a cons cell, for which the car is a session number and the cdr
+is a buffer entry (ie. a tab) within that session. In that case
+delete the buffer entry."
   (if (consp num)
-      ; When num is a cons cell, we are not dealing with a session,
-      ; but with a single buffer entry (ie. a tab) within a session
-      (let* ((item (nth 2 (nth (car num) sessions)))
+    (let* ((item (nth 2 (nth (car num) sessions)))
 	     (tmp (delq (nth (cdr num) item) item)))
 	(setf (nth 2 (nth (car num) sessions)) tmp))
     (setq sessions (delq (nth num sessions) sessions)))