[elpa] externals/hyperbole dfb9f23777: Doc strings within 80 char limit for kview.el (#233)

[ELPA Syncer]

branch: externals/hyperbole
commit dfb9f23777b37bd8d615a9e26d17a1275c0be269
Author: Mats Lidell <mats.lidell@lidells.se>
Commit: GitHub <noreply@github.com>

    Doc strings within 80 char limit for kview.el (#233)
---
 ChangeLog     |  4 +++
 kotl/kview.el | 92 ++++++++++++++++++++++++++++++++++++-----------------------
 2 files changed, 61 insertions(+), 35 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 63eb3f9397..866aca705f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2022-10-09  Mats Lidell  <matsl@gnu.org>
+
+* kotl/kview.el: Shorten docs strings to be within 80 char limit.
+
 2022-10-08  Mats Lidell  <matsl@gnu.org>
 
 * hibtypes.el (ipython-stack-frame, ripgrep-msg): Use
diff --git a/kotl/kview.el b/kotl/kview.el
index 127917bd2c..055bb22ee3 100644
--- a/kotl/kview.el
+++ b/kotl/kview.el
@@ -3,7 +3,7 @@
 ;; Author:       Bob Weiner
 ;;
 ;; Orig-Date:    6/30/93
-;; Last-Mod:     29-Aug-22 at 00:15:19 by Bob Weiner
+;; Last-Mod:      3-Oct-22 at 22:22:09 by Mats Lidell
 ;;
 ;; Copyright (C) 1993-2022  Free Software Foundation, Inc.
 ;; See the "../HY-COPY" file for license information.
@@ -51,7 +51,7 @@ Labels are padded with spaces on the left.  Default value is 
4."
   :group 'hyperbole-koutliner)
 
 (defcustom kview:default-label-separator ". "
-  "*Default string of characters to insert between label and contents of a 
koutline cell.
+  "*Default characters to insert between label and contents of a kcell.
 Default value is \". \"."
   :type 'string
   :group 'hyperbole-koutliner)
@@ -121,7 +121,8 @@ Return t unless no such cell."
   (kproperty:get (kcell-view:plist-point pos) 'kcell))
 
 (defun kcell-view:cell-from-ref (cell-ref)
-  "Return a kcell referenced by CELL-REF, a cell label, id string or integer 
idstamp.
+  "Return a kcell referenced by CELL-REF, a cell label, id string or idstamp.
+  If an idstamp, it must be an integer.
 Trigger an error if CELL-REF is not a string or is not found."
   (if (or (stringp cell-ref)
          (integerp cell-ref))
@@ -193,7 +194,7 @@ a cell's label and the start of its contents."
   (kcell-view:expand pos lbl-sep-len t))
 
 (defun kcell-view:invisible-p (&optional pos lbl-sep-len)
-  "Return t if cell at optional POS or point is entirely invisible within the 
current view.
+  "Return t if cell at optional POS or point is entirely invisible in current 
view.
 Optional LBL-SEP-LEN is the length of the separation between
 a cell's label and the start of its contents.
 
@@ -222,7 +223,8 @@ Any cell that is invisible is also collapsed as indicated 
by a call to
        "\\1" (buffer-substring start end)))))
 
 (defun kcell-view:create (kview cell contents level idstamp klabel &optional 
no-fill sibling-p)
-  "Insert into KVIEW at point, CELL with CONTENTS at LEVEL (1 = first level) 
with IDSTAMP and KLABEL.
+  "Insert into KVIEW at point, CELL with CONTENTS at LEVEL with IDSTAMP and 
KLABEL.
+First level is 1.
 If the current view displays klabels, then KLABEL should be inserted
 prior to this call, with point following it.
 
@@ -417,7 +419,7 @@ Return t unless no next cell."
     t))
 
 (defun kcell-view:next-invisible-p (&optional _pos lbl-sep-len)
-  "Return t if there is a next cell after optional POS or point and it is 
invisible."
+  "Return t if next cell after optional POS or point exists and is invisible."
   (save-excursion (and (kcell-view:next nil lbl-sep-len)
                       (kcell-view:invisible-p (point) lbl-sep-len))))
 
@@ -464,11 +466,13 @@ Return t unless no previous cell."
   (kcell:plist (kcell-view:cell pos)))
 
 (defun kcell-view:plist-point (&optional pos)
-  "Return buffer position of attributes associated with cell at optional POS 
or point."
+  "Return buffer position of attributes associated with cell.
+Cell is at optional POS or point."
   (save-excursion (1+ (kcell-view:to-label-end pos))))
 
 (defun kcell-view:to-label-end (&optional pos)
-  "Move point from optional POS to the end of the current cell's label (before 
the label separator) and return point.
+  "Move point from optional POS to end of current cell's label and return 
point.
+Point is set at end of cell's label but before the label separator.
 If between kcells, move to the previous one.  The current cell may be hidden."
   (when pos (goto-char pos))
   (if (save-excursion
@@ -488,7 +492,7 @@ If between kcells, move to the previous one.  The current 
cell may be hidden."
        (error "(kcell-view:to-label-end): Can't find end of current cell's 
label")))))
 
 (defun kcell-view:absolute-reference (&optional pos)
-  "Return a klink to the kcell at optional POS or point; return nil if not in 
a kcell.
+  "Return a klink to kcell at optional POS or point; return nil if not in a 
kcell.
 The reference is a string of the form, \"<kcell-file, cell-ref>\"
 where cell-ref is as described in the documentation for
 `kcell:ref-to-id'.  Kcell-file is an absolute path to the current
@@ -499,7 +503,7 @@ Koutline file."
             (kcell-view:label pos) (kcell-view:idstamp pos)))))
 
 (defun kcell-view:reference (&optional pos relative-dir)
-  "Return a klink to the kcell at optional POS or point; return nil if not in 
a kcell.
+  "Return a klink to kcell at optional POS or point; return nil if not in a 
kcell.
 The reference is a string of the form, \"<kcell-file, cell-ref>\"
 where cell-ref is as described in the documentation for
 `kcell:ref-to-id'.  Kcell-file is made relative to optional
@@ -511,7 +515,8 @@ or is nil), before it is returned."
             (kcell-view:label pos) (kcell-view:idstamp pos)))))
 
 (defun kcell-view:remove-attr (attribute &optional pos)
-  "Remove ATTRIBUTE, if any, for current cell or cell at optional POS.  Return 
the modified cell."
+  "Remove ATTRIBUTE, if any, for cell and return the modified cell.
+Cell is current or at optional POS."
   (interactive "*SAttribute to remove: ")
   (unless (eq attribute 'idstamp) ;; Can't remove idstamp
     (let (mod-cell)
@@ -525,7 +530,8 @@ or is nil), before it is returned."
       mod-cell)))
 
 (defun kcell-view:set-attr (attribute value &optional pos)
-  "Set ATTRIBUTE's VALUE for current cell or cell at optional POS and return 
the modified cell.
+  "Set ATTRIBUTE's VALUE for cell and return the modified cell.
+Cell is current or at optional POS.
 Use 0 for POS to set top cell's attributes."
   (unless (and (eq pos 0) (eq attribute 'idstamp)) ;; top cell idstamp set 
when Koutline is created
     (save-excursion
@@ -561,7 +567,8 @@ With optional VISIBLE-P, consider only visible siblings."
        (or lbl-sep-len (kview:label-separator-length kview)))))
 
 (defun kcell-view:to-visible-label-end (&optional pos)
-  "Move point to the end of the current visible cell's label (before the label 
separator).
+  "Move point to end of the visible cell's label.
+Cell is current or at optional POS.  Point is set before the label separator.
 If between kcells, move to the previous one.  Return final point location."
   (when pos
     (goto-char pos))
@@ -633,9 +640,10 @@ level."
                         label-type level-indent label-separator
                         label-min-width blank-lines levels-to-show 
lines-to-show)
   "Return a new kview for BUFFER-NAME.
-Optional ID-COUNTER is the maximum permanent id previously given out in this
-outline.  Optional LABEL-TYPE, LEVEL-INDENT, LABEL-SEPARATOR, LABEL-MIN-WIDTH,
-BLANK-LINES, LEVELS-TO-SHOW, and LINES-TO-SHOW may also be given, otherwise 
default values are used.
+Optional ID-COUNTER is the maximum permanent id previously utilized in this 
outline.
+Optional LABEL-TYPE, LEVEL-INDENT, LABEL-SEPARATOR, LABEL-MIN-WIDTH,
+BLANK-LINES, LEVELS-TO-SHOW, and LINES-TO-SHOW may also be given;
+otherwise, default values are used.
 
   See documentation of:
  `kview:default-label-type' for LABEL-TYPE,
@@ -718,7 +726,9 @@ this function is called."
     (set-marker opoint nil)))
 
 (defun kview:first-invisible-point (&optional pos)
-  "Return the first point following optional POS that is followed by an 
invisible character, else the end point of the cell contents.
+  "Return the first point that is followed by an invisible character.
+Start from point or optional POS.  If none are found, return the
+end point of the cell contents.
 Value may be the character immediately after point."
   (unless pos
     (setq pos (point)))
@@ -732,8 +742,8 @@ Value may be the character immediately after point."
     (or pos end)))
 
 (defun kview:first-visible-point (&optional pos)
-  "Return the first point following optional POS that is followed by a visible 
character, else (point-max).
-Value may be the character immediately after point."
+  "Return the first point that is followed by a visible character.
+Start from point or optional POS.  If not found, return (point-max)."
   (unless pos
     (setq pos (point)))
   (while (and pos (kview:char-invisible-p pos))
@@ -745,7 +755,9 @@ Value may be the character immediately after point."
   (or pos (point-max)))
 
 (defun kview:get-cells-status (kview start end)
-  "In the current buffer's KVIEW, between START and END, return a coded list 
of status of each visible cell.
+  "In current buffer's KVIEW, return a coded list of status of each visible 
cell.
+Return the list between START and END.
+
 Status is returned as: 0 if all the lines of the cell are visible and
 it has no hidden branches; a positive count of the lines displayed in
 the cell if it has no hidden branches; otherwise, a negative count of
@@ -764,7 +776,8 @@ the lines displayed, since it has hidden branches."
    kview t start end))
 
 (defun kview:goto-cell-id (idstamp-or-string)
-  "Move point to start of cell with permanent IDSTAMP-OR-STRING and return t, 
else nil."
+  "Move point to start of cell with permanent IDSTAMP-OR-STRING.
+On success, return t, else nil."
   (let* ((idstamp (if (integerp idstamp-or-string)
                      idstamp-or-string
                    (string-to-number idstamp-or-string)))
@@ -791,7 +804,8 @@ the lines displayed, since it has hidden branches."
       (kcell-view:label))))
 
 (defun kview:insert-contents (kcell contents no-fill fill-prefix)
-  "Insert KCELL's CONTENTS into view at point and fill resulting paragraphs, 
unless NO-FILL is non-nil.
+  "Insert KCELL's CONTENTS into view at point and fill resulting paragraphs.
+Do not fill if NO-FILL is non-nil.
 FILL-PREFIX is the indentation string for the current cell.  If
 CONTENTS is nil, get contents from the cell at point.  Return contents
 inserted (this value may differ from the value passed in) due to
@@ -847,7 +861,8 @@ filling."
     (kview:get-attr kview 'kotl)))
 
 (defun kview:label (klabel-function prev-label child-p)
-  "Return label string to display for current cell computed from 
KLABEL-FUNCTION, PREV-LABEL and CHILD-P."
+  "Return label string to display for current cell.
+Label is computed from KLABEL-FUNCTION, PREV-LABEL and CHILD-P."
   (funcall klabel-function prev-label child-p))
 
 (defun kview:label-function (kview)
@@ -887,7 +902,8 @@ See documentation for kview:default-level-indent."
     (kview:get-attr kview 'level-indent)))
 
 (defun kview:map-branch (func kview &optional first-p visible-p)
-  "Apply FUNC to the sibling trees from point forward within KVIEW and return 
results as a list.
+  "Apply FUNC to the sibling trees from point forward within KVIEW.
+Return results as a list.
 With optional FIRST-P non-nil, begins with first sibling in current branch.
 With optional VISIBLE-P, considers only those sibling cells that are visible
 in the view.
@@ -958,7 +974,8 @@ See also `kview:map-tree', `kview:map-branch’, and 
‘kview:map-siblings’."
              (t (error "(kview:map-region): No region or invalid start and end 
positions")))))))
 
 (defun kview:map-siblings (func kview &optional first-p visible-p)
-  "Apply FUNC to the sibling cells from point forward within KVIEW and return 
results as a list.
+  "Apply FUNC to the sibling cells from point forward within KVIEW.
+Return results as a list.
 With optional FIRST-P non-nil, begins with first sibling in current branch.
 With optional VISIBLE-P, considers only those sibling cells that are visible
 in the view.
@@ -991,7 +1008,8 @@ See also `kview:map-branch' and `kview:map-tree'."
        (nreverse results)))))
 
 (defun kview:map-expanded-tree (func kview &optional top-p)
-  "Temporarily expand the tree at point, apply FUNC to the tree in the KVIEW 
and return results as a list.
+  "Temporarily expand the tree at point, apply FUNC to the tree in the KVIEW.
+Return results as a list.
 This is for a FUNC that requires all cells in the tree be fully visible and
 expanded before operating upon it.  If this is not the case, use
 `kview:map-tree' instead.  FUNC may not change the number of or the order of
@@ -1048,7 +1066,7 @@ See also `kview:map-region', `kview:map-branch' and 
`kview:map-siblings'."
          (nreverse results)))))
 
 (defun kview:map-tree (func kview &optional top-p visible-p)
-  "Apply FUNC to the tree starting at point within KVIEW and return results as 
a list.
+  "Apply FUNC to the tree starting at point within KVIEW; return results as a 
list.
 With optional TOP-P non-nil, maps over all of kview's cells.
 With optional VISIBLE-P, considers only those cells that are visible in the
 view.
@@ -1087,7 +1105,8 @@ See also `kview:map-region', `kview:map-branch' and 
`kview:map-siblings'."
 
 (defun kview:move (from-start from-end to-start from-indent to-indent
                   &optional copy-p fill-p)
-  "Move tree between FROM-START and FROM-END to TO-START, changing FROM-INDENT 
to TO-INDENT.
+  "Move tree between FROM-START and FROM-END to TO-START.
+Also change indentation from FROM-INDENT to TO-INDENT.
 Copy tree if optional COPY-P is non-nil.  Refill cells if optional
 FILL-P is non-nil.  Leave point at TO-START."
   (let ((region (buffer-substring from-start from-end))
@@ -1157,7 +1176,8 @@ FILL-P is non-nil.  Leave point at TO-START."
     (set-marker new-start nil)))
 
 (defun kview:previous-visible-point (&optional pos)
-  "Return the first point preceding optional POS that is followed by a visible 
character, else (point-min).
+  "Return the first preceding point that is followed by a visible character.
+Start from point or optional POS.  If not found, return (point-min).
 Value may be the character immediately after point."
   (unless pos
     (setq pos (point)))
@@ -1181,7 +1201,8 @@ Value may be the character immediately after point."
     (error "(kview:set-buffer): Invalid kview argument")))
 
 (defun kview:set-cells-status (kview start end cell-status-list)
-  "In the current buffer's KVIEW, between START and END, use CELL-STATUS-LIST 
to restore each cell's status.
+  "Restore each cell's status in current buffer's KVIEW between START and END.
+Set each cell status from CELL-STATUS-LIST.
 Status is: 0 if all the lines of the cell are visible and it has no
 hidden branches; a positive count of the lines displayed in the cell
 if it has no hidden branches; otherwise, a negative count of the lines
@@ -1240,12 +1261,12 @@ valid values of NEW-TYPE."
       (kvspec:update t))))
 
 (defun kview:top-cell (kview)
-  "Return KVIEW's invisible top cell with idstamp 0 or nil if argument is not 
a kview."
+  "Return KVIEW's invisible top cell with idstamp 0 or nil if not a kview."
   (when (kview:is-p kview)
     (kview:get-attr kview 'top-cell)))
 
 (defun kview:valid-position-p (&optional pos)
-  "Return non-nil iff point or optional POS is at a position where editing may 
occur.
+  "Return non-nil iff point or optional POS is where editing may occur.
 The read-only positions between cells and within cell indentations are 
invalid."
   (when (cond ((null pos)
               (>= (current-column) (kcell-view:indent)))
@@ -1274,7 +1295,7 @@ or marker, `%s'" pos))
   (cadr (memq attribute (cadr (memq 'plist obj)))))
 
 (defun kcell-view:next-kcell (&optional visible-p lbl-sep-len)
-  "Move to the point holding the kcell property within the next cell of the 
current kview.
+  "Move to point holding the kcell property within next cell of the current 
kview.
 With optional VISIBLE-P, consider only visible cells.  Return t
 unless no next cell."
   (let* ((opoint (point))
@@ -1287,7 +1308,7 @@ unless no next cell."
        (progn (goto-char pos) t))))
 
 (defun kcell-view:previous-kcell (&optional visible-p lbl-sep-len)
-  "Move to the point holding the kcell property within the previous cell of 
the current kview.
+  "Move to point holding the kcell property within previous cell of current 
kview.
 With optional VISIBLE-P, consider only visible cells.  Return t
 unless no previous cell."
   (when (not (kview:valid-position-p))
@@ -1324,7 +1345,8 @@ unless no previous cell."
   (kview:set-attr kview 'label-parent (klabel-type:parent label-type)))
 
 (defun kview:set-label-separator (label-separator &optional set-default-p)
-  "Set the LABEL-SEPARATOR (a string) between labels and cell contents for the 
current kview.
+  "Set the LABEL-SEPARATOR between labels and cell contents for the current 
kview.
+The LABEL-SEPARATOR is a string.
 With optional prefix arg SET-DEFAULT-P, the default separator value used for
 new outlines is also set to this new value."
   (interactive