diff options
author | Eric Abrahamsen <eric@ericabrahamsen.net> | 2017-09-29 13:58:04 -0700 |
---|---|---|
committer | Eric Abrahamsen <eric@ericabrahamsen.net> | 2017-10-21 19:22:22 -0700 |
commit | 73dda4e0b45a1f831d5f990fb29e958a76ccc518 (patch) | |
tree | c72e3ffe7fd751597727059be2c7cfe66f33d846 | |
parent | 92045f4546b9708dc9f69954799d211c1f56ff1e (diff) | |
download | emacs-scratch/gnus-docs.tar.gz |
Add more comments and docstrings to Gnus source filesscratch/gnus-docs
-rw-r--r-- | lisp/gnus/gnus-group.el | 2 | ||||
-rw-r--r-- | lisp/gnus/gnus-int.el | 26 | ||||
-rw-r--r-- | lisp/gnus/gnus-start.el | 48 | ||||
-rw-r--r-- | lisp/gnus/gnus.el | 22 | ||||
-rw-r--r-- | lisp/gnus/nnheader.el | 18 | ||||
-rw-r--r-- | 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 985efe6272f..94e32e778b2 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 0c7381286cd..4bd66a0cb3a 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 3c3c594fe7b..c47e3459b56 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 8c0846be9f7..eaaf01b9b26 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 0ea99d53a4a..036945fed06 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 be38f8d1d75..4f066939d25 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)) |