Commit 73dda4e0 authored by Eric Abrahamsen's avatar Eric Abrahamsen

Add more comments and docstrings to Gnus source files

parent 92045f45
Pipeline #28 failed with stage
......@@ -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.
......@@ -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."
(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."
(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)
......@@ -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
"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))
;; 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)
......@@ -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.
......@@ -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)
......@@ -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."
(if (assq ',backend nnoo-definition-alist)
(setcar (cdr (assq ',backend nnoo-definition-alist))
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment