[Emacs-diffs] scratch/gnus-docs 73dda4e: Add more comments and docstrings to Gnus source files

[Eric Abrahamsen]

branch: scratch/gnus-docs
commit 73dda4e0b45a1f831d5f990fb29e958a76ccc518
Author: Eric Abrahamsen <address@hidden>
Commit: Eric Abrahamsen <address@hidden>

    Add more comments and docstrings to Gnus source files
---
 lisp/gnus/gnus-group.el |  2 +-
 lisp/gnus/gnus-int.el   | 26 ++++++++++++++++++++++++--
 lisp/gnus/gnus-start.el | 48 +++++++++++++++++++++++++++++++++++++++++++-----
 lisp/gnus/gnus.el       | 22 +++++++++++++++++++---
 lisp/gnus/nnheader.el   | 18 +++++++++++++++++-
 lisp/gnus/nnoo.el       | 36 ++++++++++++++++++++++++++++++++++--
 6 files changed, 138 insertions(+), 14 deletions(-)

diff --git a/lisp/gnus/gnus-group.el b/lisp/gnus/gnus-group.el
index 985efe6..94e32e7 100644
--- a/lisp/gnus/gnus-group.el
+++ b/lisp/gnus/gnus-group.el
@@ -2080,7 +2080,7 @@ that group."
      no-article nil no-display nil select-articles)))
 
 (defun gnus-group-select-group (&optional all)
-  "Select this newsgroup.
+  "Read news in this newsgroup.
 No article is selected automatically.
 If the group is opened, just switch the summary buffer.
 If ALL is non-nil, already read articles become readable.
diff --git a/lisp/gnus/gnus-int.el b/lisp/gnus/gnus-int.el
index 0c738128..4bd66a0 100644
--- a/lisp/gnus/gnus-int.el
+++ b/lisp/gnus/gnus-int.el
@@ -22,6 +22,25 @@
 
 ;;; Commentary:
 
+;; Together with nnoo.el, this file defines the basic behavior of
+;; Gnus' backends.  General server functions like `gnus-open-server'
+;; and `gnus-request-set-mark' all have a common behavior:
+
+;; 1. They accept a server as an argument, or else accept a group as
+;;    an argument and find the server from the group.
+
+;; 2. For functions that aren't mandatory, they see if the server
+;;    implements the function in question, using
+;;    `gnus-check-backend-function'.
+
+;; 3. They get the server-specific version of the function with
+;;    `gnus-get-function', and call it with `funcall'.  Ie,
+;;    `gnus-open-server' finds its function with:
+
+;;    (gnus-get-function server 'open-server)
+
+;;    and funcalls it.
+
 ;;; Code:
 
 (eval-when-compile (require 'cl))
@@ -605,7 +624,7 @@ from other groups -- for instance, search results and the 
like."
           (gnus-try-warping-via-registry)))))
 
 (defun gnus-request-head (article group)
-  "Request the head of ARTICLE in GROUP."
+  "Request the head (ie headers) of ARTICLE in GROUP."
   (let* ((gnus-command-method (gnus-find-method-for-group group))
         (head (gnus-get-function gnus-command-method 'request-head t))
         res clean-up)
@@ -845,7 +864,10 @@ If GROUP is nil, all groups on GNUS-COMMAND-METHOD are 
scanned."
     result))
 
 (defun gnus-close-backends ()
-  ;; Send a close request to all backends that support such a request.
+  "Send a close request to all backends that support closing."
+  ;; Why would this use `gnus-valid-select-methods', when those aren't
+  ;; actually servers?  How is this different from what
+  ;; `gnus-group-suspend' does?
   (let ((methods gnus-valid-select-methods)
        (gnus-inhibit-demon t)
        func gnus-command-method)
diff --git a/lisp/gnus/gnus-start.el b/lisp/gnus/gnus-start.el
index 3c3c594..c47e345 100644
--- a/lisp/gnus/gnus-start.el
+++ b/lisp/gnus/gnus-start.el
@@ -22,6 +22,37 @@
 
 ;;; Commentary:
 
+;; This file contains all the code necessary to get Gnus up and
+;; running.  The main entrypoint is `gnus-1', which clears any
+;; existing variables and re-loads from the various init files.  The
+;; most important steps in `gnus-1' are:
+
+;; 1. Read the "gnus.el" init file with `gnus-read-init-file'.
+;; 2. Run `gnus-start-news-server' to open the server listed in
+;;    `gnus-select-method'.
+;; 3. Call `gnus-setup-news', which is the heart of startup, see
+;;    below.
+;; 4. Set up the *Group* buffer and mode and list of groups, etc.
+
+;; The function `gnus-setup-news' does the next level of work.  It
+;; does two main things: first it calls `gnus-read-newsrc-file', which
+;; reads the ".newsrc.eld" file and sets the variable
+;; `gnus-newsrc-alist', holding all known groups and their marks, and
+;; eventually calls `gnus-make-hashtable-from-newsrc-alist', which
+;; uses `gnus-newsrc-alist' to populate `gnus-newsrc-hashtb'.
+
+;; Later, it calls `gnus-get-unread-articles', which is also the
+;; function called anytime the user "updates" Gnus with "g" in the
+;; Group buffer.  `gnus-get-unread-articles' first decides which
+;; groups should be updated, then calls
+;; `gnus-get-unread-articles-in-group' on each one.  This updates the
+;; group's active and marks information.
+
+;; There are also `gnus-activate-group', which may or may not also
+;; request a scan of the group.  We're currently investigating what
+;; these terms actually mean.
+
+
 ;;; Code:
 
 (require 'gnus)
@@ -840,7 +871,9 @@ prompt the user for the name of an NNTP server to use."
 ;;;
 
 (defvar gnus-dribble-ignore nil)
-(defvar gnus-dribble-eval-file nil)
+(defvar gnus-dribble-eval-file nil
+  "When non-nil, the dribble file should be read.
+This flag is set in `gnus-1', and checked by `gnus-setup-news'.")
 
 (defun gnus-dribble-file-name ()
   "Return the dribble file for the current .newsrc."
@@ -1463,6 +1496,7 @@ newsgroup."
          (when (> (cdr cache-active) (cdr active))
            (setcdr active (cdr cache-active))))))))
 
+;;FIXME: What does "activate" actually MEAN?
 (defun gnus-activate-group (group &optional scan dont-check method
                                  dont-sub-check)
   "Check whether a group has been activated or not.
@@ -1614,9 +1648,10 @@ backend check whether the group actually exists."
        (setcar (gnus-group-entry (gnus-info-group info)) num))
       num)))
 
-;; Go though `gnus-newsrc-alist' and compare with `gnus-active-hashtb'
-;; and compute how many unread articles there are in each group.
 (defun gnus-get-unread-articles (&optional level dont-connect one-level)
+  "Go though `gnus-newsrc-alist' and compare with
+`gnus-active-hashtb' and compute how many unread articles there
+are in each group."
   (setq gnus-server-method-cache nil)
   (require 'gnus-agent)
   (let* ((newsrc (cdr gnus-newsrc-alist))
@@ -1838,9 +1873,12 @@ backend check whether the group actually exists."
       (dolist (info infos)
        (gnus-activate-group (gnus-info-group info) nil nil method t))))))
 
-;; Create a hash table out of the newsrc alist.  The `car's of the
-;; alist elements are used as keys.
 (defun gnus-make-hashtable-from-newsrc-alist ()
+  "Create a hash table out of the newsrc alist.
+For each element in `gnus-newsrc-alist', representing a group and
+its marks, create an equivalent entry in `gnus-newsrc-hashtb'.
+If there was already an entry for the group in the hashtable,
+preserve the original entry's unread counts."
   (let ((alist gnus-newsrc-alist)
        (ohashtb gnus-newsrc-hashtb)
        prev info method rest methods)
diff --git a/lisp/gnus/gnus.el b/lisp/gnus/gnus.el
index 8c0846b..eaaf01b 100644
--- a/lisp/gnus/gnus.el
+++ b/lisp/gnus/gnus.el
@@ -1161,7 +1161,21 @@ REST is a plist of following:
 :variable-document  The documentation for the variable.
 :variable-group     The group for customizing the variable.
 :variable-type      The type for customizing the variable.
-:variable-default   The default value of the variable."
+:variable-default   The default value of the variable.
+
+This macro can define several things for PARAM: a group
+parameter, a function accessor, and a variable.  The parameter
+has the name PARAM, which is what will be stored in
+`gnus-newsrc-alist'.  The function accesssor returns the value of
+the parameter when called with a group as its only argument.  The
+variable is by default named `gnus-parameter-PARAM-alist', and
+holds a list of '(regexp value) pairs, where the regexp is
+matched again group names, and value is the default value for
+matched groups.
+
+In other words, PARAM is set for a single group, while
+`gnus-parameter-PARAM-alist' works the other way, by providing
+default parameter values for whole classes of matching groups."
   (let* ((type (plist-get rest :type))
         (parameter-type (plist-get rest :parameter-type))
         (parameter-document (plist-get rest :parameter-document))
@@ -2689,8 +2703,10 @@ such as a mark that says whether an article is stored in 
the cache
   "Gnus variables saved in the quick startup file.")
 
 (defvar gnus-newsrc-alist nil
-  "Assoc list of read articles.
-`gnus-newsrc-hashtb' should be kept so that both hold the same information.")
+  "Assoc list of groups and their info.
+Each element is a list of group name, marks and article numbers,
+and other parameters set by the user.  `gnus-newsrc-hashtb'
+should be kept so that both hold the same information.")
 
 (defvar gnus-registry-alist nil
   "Assoc list of registry data.
diff --git a/lisp/gnus/nnheader.el b/lisp/gnus/nnheader.el
index 0ea99d5..036945f 100644
--- a/lisp/gnus/nnheader.el
+++ b/lisp/gnus/nnheader.el
@@ -24,6 +24,19 @@
 
 ;;; Commentary:
 
+;; This file implements communication with the (slightly-misnamed)
+;; `nntp-server-buffer'.  When Gnus sends requests to the backends,
+;; they insert their responses into this buffer, and the various
+;; `nnheader-*' functions read and parse those responses.  The
+;; responses might be control strings like "211 OK", and they might be
+;; full article headers and bodies.  Some backend's server responses
+;; are only interpretable by that backend; they still use this buffer
+;; to insert server responses, but then read (and remove) those
+;; responses themselves.
+
+;; Failure to clear this buffer, or to set point correctly, is an easy
+;; Gnus bug.
+
 ;;; Code:
 
 (eval-when-compile (require 'cl))
@@ -564,7 +577,10 @@ the line could be found."
 
 ;; Various cruft the backends and Gnus need to communicate.
 
-(defvar nntp-server-buffer nil)
+(defvar nntp-server-buffer nil
+  "Buffer used for communication with server backends.
+When Gnus sends a request to the various servers, they insert
+their responses into this buffer.")
 (defvar nntp-process-response nil)
 
 (defvar nnheader-callback-function nil)
diff --git a/lisp/gnus/nnoo.el b/lisp/gnus/nnoo.el
index be38f8d..4f06693 100644
--- a/lisp/gnus/nnoo.el
+++ b/lisp/gnus/nnoo.el
@@ -22,13 +22,42 @@
 
 ;;; Commentary:
 
+;; This file defines Gnus' non-object-oriented polymorphism scheme for
+;; server backends.  It allows the rest of the code to be relatively
+;; agnostic about how particular backends (eg IMAP, maildir, nntp,
+;; etc) actually work: it simply calls standard functions on them, and
+;; retrieves standard variable values from them.
+
+;; New backends are created using `nnoo-declare' (functionally
+;; equivalent to `defclass').  The macro `defvoo' creates server
+;; variables (equivalent to slots in EIEIO).  The macro `deffoo'
+;; creates server functions (equivalent to generic methods).
+
+;; The Gnus manual goes into fair detail about this
+;; inheritance/polymorphism system, see (info "(gnus) Writing New Back
+;; Ends").
+
+;; Any time the user switches servers, the function
+;; `nnoo-change-servers' copies all the relevant server variables into
+;; global variables, to make that server the "current server".
+
 ;;; Code:
 
 (require 'nnheader)
 (eval-when-compile (require 'cl))
 
-(defvar nnoo-definition-alist nil)
-(defvar nnoo-state-alist nil)
+(defvar nnoo-definition-alist nil
+  "A list of all available server backends.
+All backends that have been defined with `nnoo-declare' appear
+here.  Each backend appears as a list of four elements: the
+symbol name of the backend, the parent backends it inherits from,
+a list of potential server variables, and a list of backend
+functions it implements.")
+
+(defvar nnoo-state-alist nil
+  "A list of all the current servers.
+Includes their server variables and their active groups.")
+
 (defvar nnoo-parent-backend nil)
 
 (defmacro defvoo (var init &optional doc &rest map)
@@ -57,6 +86,9 @@
     (setcar funcs (cons func (car funcs)))))
 
 (defmacro nnoo-declare (backend &rest parents)
+  "Declare BACKEND as a new backend, inheriting from PARENTS.
+Any functions or variables not implemented by BACKEND may be used
+from PARENTS instead."
   `(eval-and-compile
      (if (assq ',backend nnoo-definition-alist)
         (setcar (cdr (assq ',backend nnoo-definition-alist))