Doc strings within 80 char limit for kview.el

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

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