From e63fd26d95a7a0d7552127035f20b8e89a99580e Mon Sep 17 00:00:00 2001 From: SqrtMinusOne Date: Thu, 24 Mar 2022 00:09:34 +0300 Subject: [PATCH] docs: more docstrings --- elfeed-summary.el | 83 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 57 insertions(+), 26 deletions(-) diff --git a/elfeed-summary.el b/elfeed-summary.el index 9271cb1..59b0e98 100644 --- a/elfeed-summary.el +++ b/elfeed-summary.el @@ -28,8 +28,8 @@ ;; inspired by newsboat but tree-based. ;; ;; `elfeed-summary' pops up the summary buffer. The buffer shows -;; individual feeds and searches, combined into groups. This is -;; determined by the `elfeed-summary-settings' variable. +;; individual feeds and searches, combined into groups. The structure +;; is determined by the `elfeed-summary-settings' variable. ;; ;; Also take a look at the package README at ;; for more @@ -54,7 +54,7 @@ (declare-function rmh-elfeed-org-process "elfeed-org") (define-widget 'elfeed-summary-query 'lazy - "Type widget for the query part of `elfeed-summary-settings'." + "Type widget for the `' form of `elfeed-summary-settings'." :offset 4 :tag "Extract subset of elfeed feed list" :type '(choice (symbol :tag "One tag") @@ -171,7 +171,8 @@ This is a list of these possible items: Match if any of the conditions 1, 2, ..., n match. - `(not )' -Feed tags for query are taken from `elfeed-feeds'. +Feed tags for the query are determined by the `elfeed-feeds' +variable. Query examples: - `(emacs lisp)' @@ -189,31 +190,40 @@ Query examples: - `:tags' - list of tags to get the face of the entry. Available special forms: -- `:misc' - print out feeds, not found by any query above." +- `:misc' - print out feeds, not found by any query above. + +Also keep in mind that '(key . ((values))) is the same as '(key +(values)). This helps to shorten the form in many cases. + +Also, this variable is not validated by any means, so wrong values can +produce somewhat cryptic errors." :group 'elfeed-summary :type 'elfeed-summary-setting-elements) (defcustom elfeed-summary-look-back (* 60 60 24 180) - "Timespan for which to count entries in the feed list. + "The date range for which to count entries in the feed list. -The default value is 180 days, which means that only entries less than -180 days old will be counted. +The value is in seconds. The default value is 180 days, which means +that only entries less than 180 days old will be counted. This has to be set up for efficiency because the elfeed database is -time-based, so this allows queirying only the most recent part of the -database. - -The value is in seconds." +time-based, so this allows querying only the most recent part of the +database." :group 'elfeed-summary :type 'integer) (defcustom elfeed-summary-default-filter "@6-months-ago " - "Default filter when switching to search buffer for a feed." + "Default filter for `elfeed-search'. + +This has to end with space. The unread tag will be added +automatically." :group 'elfeed-summary :type 'integer) (defcustom elfeed-summary-unread-tag 'unread - "Tag with which to consider the entry unread." + "Tag that determines whether the entry is unread. + +Probably should be one of `elfeed-initial-tags'." :group 'elfeed-summary :type 'symbol) @@ -247,14 +257,18 @@ greater than zero." (defcustom elfeed-summary-feed-sort-fn #'elfeed-summary--feed-sort-fn "Function to sort feeds in query. -Receives two instances of `elfeed-feed'." +Accepts two instances of `elfeed-feed'. + +The default implementation does the alphabetical case-insensitive +ordering." :group 'elfeed-summary :type 'function) (defcustom elfeed-summary-refresh-on-each-update nil "Whether to refresh the elfeed summary buffer after each update. -This significantly slows down the `elfeed-update' command." +This significantly slows down the `elfeed-update' command when run +from the summary buffer." :group 'elfeed-summary :type 'boolean) @@ -484,7 +498,7 @@ PARAMS is a form as described in `elfeed-summary-settings'. UNREAD-COUNT and TOTAL-COUNT are hashmaps with feed ids as keys and corresponding numbers of entries as values. -MISC-FEEDS is a list of feeds that was not used in PARAMS. +MISC-FEEDS is a list of feeds that were not used in PARAMS. The resulting form is described in `elfeed-summary--get-data'." (cl-loop for param in params @@ -546,7 +560,7 @@ The return value is a list of alists of the following elements: - `children' - list of children, same structure as the root form. `' is an alist with the following keys: -- `feed' - instance of `elfeed-feed'. +- `feed' - an instance of `elfeed-feed'. - `tags' - feed tags. - `faces' - list of faces for the search entry. - `unread' - number of unread entries in the feed. @@ -638,7 +652,19 @@ The return value is a list of alists of the following elements: ((group :initform nil))) (defun elfeed-summary--action (pos &optional event) - "Open thing at point in the elfeed summary buffer." + "Run action at thing at the point in the elfeed summary buffer. + +If there's a widget at the point, pass the press event to the widget. +That should result in the call to +`elfeed-summary--search-feed-notify'. Otherwise, if there's a group +section, run the corresponding action for the group. + +The behavior of both `elfeed-summary--search-feed-notify' and +`elfeed-summary--open-section' is modified by lexically scoped +variables `elfeed-summary--search-show-read' and +`elfeed-summary--search-mark-read'. + +POS and EVENT are forwarded to `widget-button-press'." (interactive "@d") (cond ((get-char-property pos 'button) (widget-button-press pos event)) @@ -648,7 +674,7 @@ The return value is a list of alists of the following elements: (elfeed-summary--open-section (magit-current-section))))) (defun elfeed-summary--action-show-read (pos &optional event) - "Press a button with `elfeed-summary--search-show-read' set to t. + "Run action with `elfeed-summary--search-show-read' set to t. POS and EVENT are forwarded to `widget-button-press'." (interactive "@d") @@ -656,7 +682,7 @@ POS and EVENT are forwarded to `widget-button-press'." (elfeed-summary--action pos event))) (defun elfeed-summary--action-mark-read (pos &optional event) - "Press a button with `elfeed-summary--search-mark-read' set to t. + "Run action with `elfeed-summary--search-mark-read' set to t. POS and EVENT are forwarded to `widget-button-press'." (interactive "@d") @@ -664,7 +690,7 @@ POS and EVENT are forwarded to `widget-button-press'." (elfeed-summary--action pos event))) (defun elfeed-summary--mark-read (feeds) - "Mark all the FEEDS items as read. + "Mark all the entries in FEEDS as read. FEEDS is a list of instances of `elfeed-feed'." (when (or (not elfeed-summary-confirm-mark-read) @@ -688,7 +714,7 @@ items." elfeed-summary-default-filter (unless (or elfeed-summary--search-show-read show-read) - "+unread ") + (format "+%s " elfeed-summary-unread-tag)) "=" (replace-regexp-in-string (rx "?" (* not-newline) eos) @@ -733,7 +759,7 @@ SECTION is an instance of `magit-section'." (concat elfeed-summary-default-filter (unless elfeed-summary--search-show-read - "+unread ") + (format "+%s " elfeed-summary-unread-tag)) (mapconcat (lambda (feed) (format "=%s" (replace-regexp-in-string @@ -1016,8 +1042,13 @@ search buffer." (defun elfeed-summary () "Display a feed summary for elfeed. -The buffer displays a list of feeds, as set up by the -`elfeed-summary-settings' variable." +The feed summary is a tree of three basic items: groups, feeds and +searches. Groups also may contain other items. The structure of the +tree is determined by the `elfeed-summary-settings' variable. + +Take a look at `elfeed-summary-mode' for the list of available +keybindings, and at the `elfeed-summary' group for the available +options." (interactive) (elfeed-summary--ensure) (unless elfeed-summary--setup