[elpa] externals/org 6f960f3c6a 2/2: * lisp/org-element.el: Fix checkdoc warnings

[ELPA Syncer]

branch: externals/org
commit 6f960f3c6a4dfe137fbd33fef9f7dadfd229600c
Author: Ihor Radchenko <yantar92@posteo.net>
Commit: Ihor Radchenko <yantar92@posteo.net>

    * lisp/org-element.el: Fix checkdoc warnings
    
    (org-element-inlinetask-parser): Document LIMIT function argument.
    (org-element--list-struct): Add docstring.
    (org-element-map): Capitalize Lisp.
    (org-element--cache-diagnostics-ring): Make docstring 80 chars wide
    with single sentence as the first line.
    (org-element--cache-log-message):
    (org-element--cache-warn):
    (org-element--cache-active-p):
    (org-element--cache-after-change):  Document the function arguments.
    (org-element--parse-to):
    (org-element-cache-map): Do not put "." at the end of error messages.
    (org-element--cache-avoid-synchronous-headline-re-parsing): Escape (
    at bol in the docstring.
    (org-element--cache-persist-before-write):
    (org-element--cache-persist-before-read):
    (org-element--cache-persist-after-read): Add detailed docstring and
    document all the function arguments.
---
 lisp/org-element.el | 53 ++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 36 insertions(+), 17 deletions(-)

diff --git a/lisp/org-element.el b/lisp/org-element.el
index 55395be62f..f583453216 100644
--- a/lisp/org-element.el
+++ b/lisp/org-element.el
@@ -1612,6 +1612,8 @@ CONTENTS is the contents of the element."
 (defun org-element-inlinetask-parser (limit &optional raw-secondary-p)
   "Parse an inline task.
 
+Do not search past LIMIT.
+
 Return a new syntax node of `inlinetask' type containing `:title',
 `:begin', `:end', `:pre-blank', `:contents-begin' and `:contents-end',
 `:level', `:priority', `:raw-value', `:tags', `:todo-keyword',
@@ -1849,8 +1851,10 @@ CONTENTS is the contents of the element."
 ;;;; Plain List
 
 (defun org-element--list-struct (limit)
-  ;; Return structure of list at point.  Internal function.  See
-  ;; `org-list-struct' for details.
+"Return structure of list at point.
+Do not parse past LIMIT.
+
+Internal function.  See `org-list-struct' for details."
   (let ((case-fold-search t)
        (top-ind limit)
        (item-re (org-item-re))
@@ -4955,7 +4959,7 @@ one argument: the element or object itself.
 
 When TYPES is t, call FUN for all the elements and objects.
 
-FUN can also be a lisp form.  The form will be evaluated as function
+FUN can also be a Lisp form.  The form will be evaluated as function
 with symbol `node' bound to the current node.
 
 When optional argument INFO is non-nil, it should be a plist
@@ -5699,8 +5703,8 @@ to be correct.  Setting this to a value less than 0.0001 
is useless.")
   "Detail level of the diagnostics.")
 
 (defvar-local org-element--cache-diagnostics-ring nil
-  "Ring containing last `org-element--cache-diagnostics-ring-size'
-cache process log entries.")
+  "Ring containing cache process log entries.
+The ring size is `org-element--cache-diagnostics-ring-size'.")
 
 (defvar org-element--cache-diagnostics-ring-size 5000
   "Size of `org-element--cache-diagnostics-ring'.")
@@ -5852,7 +5856,8 @@ better to remove the commands advised in such a way from 
this list.")
      (prin1-to-string ,element)))
 
 (defmacro org-element--cache-log-message (format-string &rest args)
-  "Add a new log message for org-element-cache."
+  "Add a new log message for org-element-cache.
+FORMAT-STRING and ARGS are the same arguments as in `foramt'."
   `(when (or org-element--cache-diagnostics
              (eq org-element--cache-self-verify 'backtrace))
      (let* ((format-string (concat (format "org-element-cache diagnostics(%s): 
"
@@ -5867,7 +5872,8 @@ better to remove the commands advised in such a way from 
this list.")
          (ring-insert org-element--cache-diagnostics-ring format-string)))))
 
 (defmacro org-element--cache-warn (format-string &rest args)
-  "Raise warning for org-element-cache."
+  "Raise warning for org-element-cache.
+FORMAT-STRING and ARGS are the same arguments as in `format'."
   `(let* ((format-string (funcall #'format ,format-string ,@args))
           (format-string
            (if (or (not org-element--cache-diagnostics-ring)
@@ -6047,7 +6053,9 @@ This function assumes `org-element--headline-cache' is a 
valid AVL tree."
 ;; declaration on top would require restructuring the whole cache
 ;; section.
 (defun org-element--cache-active-p (&optional called-from-cache-change-func-p)
-  "Non-nil when cache is active in current buffer."
+  "Non-nil when cache is active in current buffer.
+When CALLED-FROM-CACHE-CHANGE-FUNC-P is non-nil, do not assert cache
+consistency with buffer modifications."
   (org-with-base-buffer nil
     (and org-element-use-cache
          (or org-element--cache
@@ -6915,7 +6923,7 @@ the expected result."
                  (setq org-element--cache-interrupt-C-g-count 0)
                  (org-element-cache-reset)
                  (error "org-element: Parsing aborted by user.  Cache has been 
cleared.
-If you observe Emacs hangs frequently, please report this to Org mode mailing 
list (M-x org-submit-bug-report)."))
+If you observe Emacs hangs frequently, please report this to Org mode mailing 
list (M-x org-submit-bug-report)"))
                (message (substitute-command-keys
                          "`org-element--parse-buffer': Suppressed 
`\\[keyboard-quit]'.  Press `\\[keyboard-quit]' %d more times to force 
interruption.")
                         (- org-element--cache-interrupt-C-g-max-count
@@ -7104,7 +7112,7 @@ The function returns the new value of 
`org-element--cache-change-warning'."
 
 (defun org-element--cache-after-change (beg end pre)
   "Update buffer modifications for current buffer.
-BEG and END are the beginning and end of the range of changed
+BEG, END, and PRE are the beginning and end of the range of changed
 text, and the length in bytes of the pre-change text replaced by
 that range.  See `after-change-functions' for more information."
   (org-with-base-buffer nil
@@ -7154,7 +7162,7 @@ when buffer modifications are mixed with cache requests.  
However,
 large automated edits inserting/deleting many headlines are somewhat
 slower by default (as in `org-archive-subtree').  Let-binding this
 variable to non-nil will reduce cache latency after every singular edit
-(`after-change-functions') at the cost of slower cache queries.")
+\(`after-change-functions') at the cost of slower cache queries.")
 (defun org-element--cache-for-removal (beg end offset)
   "Return first element to remove from cache.
 
@@ -7564,7 +7572,12 @@ The element is: %S\n The real element is: %S\n Cache 
around :begin:\n%S\n%S\n%S"
 ;;; Cache persistence
 
 (defun org-element--cache-persist-before-write (container &optional associated)
-  "Sync cache before saving."
+  "Sync element cache for CONTAINER and ASSOCIATED item before saving.
+This function is intended to be used in `org-persist-before-write-hook'.
+
+Prevent writing to disk cache when cache is disabled in the CONTAINER
+buffer.  Otherwise, cleanup cache sync keys, unreadable :buffer
+properties, and verify cache consistency."
   (when (equal container '(elisp org-element--cache))
     (if (and org-element-use-cache
              (plist-get associated :file)
@@ -7595,7 +7608,11 @@ The element is: %S\n The real element is: %S\n Cache 
around :begin:\n%S\n%S\n%S"
       'forbid)))
 
 (defun org-element--cache-persist-before-read (container &optional associated)
-  "Avoid reading cache before Org mode is loaded."
+  "Avoid reading cache for CONTAINER and ASSOCIATED before Org mode is loaded.
+This function is intended to be used in `org-persist-before-read-hook'.
+
+Also, prevent reading cache when the buffer CONTAINER hash is not
+consistent with the cache."
   (when (equal container '(elisp org-element--cache))
     (org-element--cache-log-message "Loading persistent cache for %s" 
(plist-get associated :file))
     (if (not (and (plist-get associated :file)
@@ -7613,7 +7630,9 @@ The element is: %S\n The real element is: %S\n Cache 
around :begin:\n%S\n%S\n%S"
           'forbid)))))
 
 (defun org-element--cache-persist-after-read (container &optional associated)
-  "Setup restored cache."
+  "Setup restored cache for CONTAINER and ASSOCIATED.
+Re-fill :buffer properties for cache elements (buffer objects cannot be 
written onto disk).
+Also, perform some consistency checks to prevent loading corrupted cache."
   (when (and (plist-get associated :file)
              (get-file-buffer (plist-get associated :file)))
     (with-current-buffer (get-file-buffer (plist-get associated :file))
@@ -7763,8 +7782,8 @@ function modified the buffer.")
 (cl-defun org-element-cache-map (func &key (granularity 'headline+inlinetask) 
restrict-elements
                                       next-re fail-re from-pos (to-pos 
(point-max-marker)) after-element limit-count
                                       narrow)
-  "Map all elements in current buffer with FUNC according to
-GRANULARITY.  Collect non-nil return values into result list.
+  "Map all elements in current buffer with FUNC according to GRANULARITY.
+Collect non-nil return values into result list.
 
 FUNC should accept a single argument - the element.
 
@@ -7810,7 +7829,7 @@ argument of FUNC.  Changes to elements made in FUNC will 
also alter
 the cache."
   (org-element-with-enabled-cache
     (unless (org-element--cache-active-p)
-      (error "Cache must be active."))
+      (error "Cache must be active"))
     (unless (memq granularity '( headline headline+inlinetask
                                  greater-element element))
       (error "Unsupported granularity: %S" granularity))