Add doc-strings to all functions.

(timeclock-workday, timeclock-in, timeclock-completing-read): Doc fixes.
(timeclock-entry-list-length, timeclock-entry-list-projects)
(timeclock-day-list-projects, timeclock-day-list): Use dolist.

2 files changed, 60 insertions, 32 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 25a2b7bc20c..6aa41858a2e 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -71,7 +71,7 @@
         (hebrew-calendar-elapsed-days, hebrew-calendar-long-heshvan-p)
         (hebrew-calendar-short-kislev-p, mark-hebrew-diary-entries)
         (insert-hebrew-diary-entry, insert-monthly-hebrew-diary-entry)
-        (insert-yearly-hebrew-diary-entry, diary-yahrzeit): Doc fixes.
+        (insert-yearly-hebrew-diary-entry, diary-yahrzeit):
         * calendar/cal-islam.el (islamic-calendar-leap-year-p)
         (list-islamic-diary-entries, mark-islamic-diary-entries)
         (insert-islamic-diary-entry, insert-monthly-islamic-diary-entry)
@@ -180,6 +180,11 @@
         (calendar-sunrise-sunset, diary-sunrise-sunset, diary-sabbath-candles):
         Use or.
 
+        * calendar/timeclock.el: Add doc-strings to all functions.
+        (timeclock-workday, timeclock-in, timeclock-completing-read): Doc fixes.
+        (timeclock-entry-list-length, timeclock-entry-list-projects)
+        (timeclock-day-list-projects, timeclock-day-list): Use dolist.
+
         * calendar/todo-mode.el: Remove un-needed eval-when-compile.
 
         * textmodes/org.el (list-diary-entries-hook): Declare for compiler.
diff --git a/lisp/calendar/timeclock.el b/lisp/calendar/timeclock.el
index a24bbab71fc..fb4a4c1afcd 100644
--- a/lisp/calendar/timeclock.el
+++ b/lisp/calendar/timeclock.el
@@ -90,7 +90,7 @@
   :group 'timeclock)
 
 (defcustom timeclock-workday (* 8 60 60)
-  "The length of a work period."
+  "The length of a work period in seconds."
   :type 'integer
   :group 'timeclock)
 
@@ -341,7 +341,7 @@ You must modify via \\[customize] for this variable to have an effect."
 (defun timeclock-in (&optional arg project find-project)
   "Clock in, recording the current time moment in the timelog.
 With a numeric prefix ARG, record the fact that today has only that
-many hours in it to be worked.  If arg is a non-numeric prefix arg
+many hours in it to be worked.  If ARG is a non-numeric prefix argument
 \(non-nil, but not a number), 0 is assumed (working on a holiday or
 weekend).  *If not called interactively, ARG should be the number of
 _seconds_ worked today*.  This feature only has effect the first time
@@ -594,7 +594,7 @@ relative only to the time worked today, and not to past time."
 OLD-DEFAULT hours are set for every day that has no number indicated."
   (interactive "P")
   (if old-default (setq old-default (prefix-numeric-value old-default))
-    (error "timelog-make-hours-explicit requires an explicit argument"))
+    (error "`timelog-make-hours-explicit' requires an explicit argument"))
   (let ((extant-timelog (find-buffer-visiting timeclock-file))
         current-date)
     (with-current-buffer (find-file-noselect timeclock-file t)
@@ -627,7 +627,9 @@ OLD-DEFAULT hours are set for every day that has no number indicated."
 (defvar timeclock-last-project nil)
 
 (defun timeclock-completing-read (prompt alist &optional default)
-  "A version of `completing-read' that works on both Emacs and XEmacs."
+  "A version of `completing-read' that works on both Emacs and XEmacs.
+PROMPT, ALIST and DEFAULT are used for the PROMPT, COLLECTION and DEF
+arguments of `completing-read'."
   (if (featurep 'xemacs)
       (let ((str (completing-read prompt alist)))
         (if (or (null str) (= (length str) 0))
@@ -745,80 +747,96 @@ This is only provided for coherency when used by
     timeclock-last-period))
 
 (defsubst timeclock-entry-length (entry)
+  "Return the length of ENTRY in seconds."
   (- (timeclock-time-to-seconds (cadr entry))
      (timeclock-time-to-seconds (car entry))))
 
 (defsubst timeclock-entry-begin (entry)
+  "Return the start time of ENTRY."
   (car entry))
 
 (defsubst timeclock-entry-end (entry)
+  "Return the end time of ENTRY."
   (cadr entry))
 
 (defsubst timeclock-entry-project (entry)
+  "Return the project of ENTRY."
   (nth 2 entry))
 
 (defsubst timeclock-entry-comment (entry)
+  "Return the comment of ENTRY."
   (nth 3 entry))
 
-
 (defsubst timeclock-entry-list-length (entry-list)
+  "Return the total length of ENTRY-LIST in seconds."
   (let ((length 0))
-    (while entry-list
-      (setq length (+ length (timeclock-entry-length (car entry-list))))
-      (setq entry-list (cdr entry-list)))
+    (dolist (entry entry-list)
+      (setq length (+ length (timeclock-entry-length entry))))
     length))
 
 (defsubst timeclock-entry-list-begin (entry-list)
+  "Return the start time of the first element of ENTRY-LIST."
   (timeclock-entry-begin (car entry-list)))
 
 (defsubst timeclock-entry-list-end (entry-list)
+  "Return the end time of the last element of ENTRY-LIST."
   (timeclock-entry-end (car (last entry-list))))
 
 (defsubst timeclock-entry-list-span (entry-list)
+  "Return the total time in seconds spanned by ENTRY-LIST."
   (- (timeclock-time-to-seconds (timeclock-entry-list-end entry-list))
      (timeclock-time-to-seconds (timeclock-entry-list-begin entry-list))))
 
 (defsubst timeclock-entry-list-break (entry-list)
+  "Return the total break time (span - length) in ENTRY-LIST."
   (- (timeclock-entry-list-span entry-list)
      (timeclock-entry-list-length entry-list)))
 
 (defsubst timeclock-entry-list-projects (entry-list)
-  (let (projects)
-    (while entry-list
-      (let ((project (timeclock-entry-project (car entry-list))))
-        (if projects
-            (add-to-list 'projects project)
-          (setq projects (list project))))
-      (setq entry-list (cdr entry-list)))
+  "Return a list of all the projects in ENTRY-LIST."
+  (let (projects proj)
+    (dolist (entry entry-list)
+      (setq proj (timeclock-entry-project entry))
+      (if projects
+          (add-to-list 'projects proj)
+        (setq projects (list proj))))
     projects))
 
-
 (defsubst timeclock-day-required (day)
+  "Return the required length of DAY in seconds, default `timeclock-workday'."
   (or (car day) timeclock-workday))
 
 (defsubst timeclock-day-length (day)
+  "Return the actual length of DAY in seconds."
   (timeclock-entry-list-length (cdr day)))
 
 (defsubst timeclock-day-debt (day)
+  "Return the debt (required - actual) associated with DAY, in seconds."
   (- (timeclock-day-required day)
      (timeclock-day-length day)))
 
 (defsubst timeclock-day-begin (day)
+  "Return the start time of DAY."
   (timeclock-entry-list-begin (cdr day)))
 
 (defsubst timeclock-day-end (day)
+  "Return the end time of DAY."
   (timeclock-entry-list-end (cdr day)))
 
 (defsubst timeclock-day-span (day)
+  "Return the span of DAY."
   (timeclock-entry-list-span (cdr day)))
 
 (defsubst timeclock-day-break (day)
+  "Return the total break time of DAY."
   (timeclock-entry-list-break (cdr day)))
 
 (defsubst timeclock-day-projects (day)
+  "Return a list of all the projects in DAY."
   (timeclock-entry-list-projects (cdr day)))
 
 (defmacro timeclock-day-list-template (func)
+  "Template for summing the result of FUNC on each element of DAY-LIST."
   `(let ((length 0))
      (while day-list
        (setq length (+ length (,(eval func) (car day-list))))
@@ -826,57 +844,62 @@ This is only provided for coherency when used by
      length))
 
 (defun timeclock-day-list-required (day-list)
+  "Return total required length of DAY-LIST, in seconds."
   (timeclock-day-list-template 'timeclock-day-required))
 
 (defun timeclock-day-list-length (day-list)
+  "Return actual length of DAY-LIST, in seconds."
   (timeclock-day-list-template 'timeclock-day-length))
 
 (defun timeclock-day-list-debt (day-list)
+  "Return total debt (required - actual) of DAY-LIST."
   (timeclock-day-list-template 'timeclock-day-debt))
 
 (defsubst timeclock-day-list-begin (day-list)
+  "Return the start time of DAY-LIST."
   (timeclock-day-begin (car day-list)))
 
 (defsubst timeclock-day-list-end (day-list)
+  "Return the end time of DAY-LIST."
   (timeclock-day-end (car (last day-list))))
 
 (defun timeclock-day-list-span (day-list)
+  "Return the span of DAY-LIST."
   (timeclock-day-list-template 'timeclock-day-span))
 
 (defun timeclock-day-list-break (day-list)
+  "Return the total break of DAY-LIST."
   (timeclock-day-list-template 'timeclock-day-break))
 
 (defun timeclock-day-list-projects (day-list)
+  "Return a list of all the projects in DAY-LIST."
   (let (projects)
-    (while day-list
-      (let ((projs (timeclock-day-projects (car day-list))))
-        (while projs
-          (if projects
-              (add-to-list 'projects (car projs))
-            (setq projects (list (car projs))))
-          (setq projs (cdr projs))))
-      (setq day-list (cdr day-list)))
+    (dolist (day day-list)
+      (dolist (proj (timeclock-day-projects day))
+        (if projects
+            (add-to-list 'projects proj)
+          (setq projects (list proj)))))
     projects))
 
-
 (defsubst timeclock-current-debt (&optional log-data)
+  "Return the seconds debt from LOG-DATA, default `timeclock-log-data'."
   (nth 0 (or log-data (timeclock-log-data))))
 
 (defsubst timeclock-day-alist (&optional log-data)
+  "Return the date alist from LOG-DATA, default `timeclock-log-data'."
   (nth 1 (or log-data (timeclock-log-data))))
 
 (defun timeclock-day-list (&optional log-data)
-  (let ((alist (timeclock-day-alist log-data))
-        day-list)
-    (while alist
-      (setq day-list (cons (cdar alist) day-list)
-            alist (cdr alist)))
+  "Return a list of the cdrs of the date alist from LOG-DATA."
+  (let (day-list)
+    (dolist (date-list (timeclock-day-alist log-data))
+      (setq day-list (cons (cdr date-list) day-list)))
     day-list))
 
 (defsubst timeclock-project-alist (&optional log-data)
+  "Return the project alist from LOG-DATA, default `timeclock-log-data'."
   (nth 2 (or log-data (timeclock-log-data))))
 
-
 (defun timeclock-log-data (&optional recent-only filename)
   "Return the contents of the timelog file, in a useful format.
 If the optional argument RECENT-ONLY is non-nil, only show the contents