; Fix doc strings in lisp/image/ directory

* lisp/image/wallpaper.el (wallpaper-setter)
(wallpaper--find-command, wallpaper--x-monitor-name)
(wallpaper--format-arg):
* lisp/image/image-dired-util.el
(image-dired-associated-dired-buffer)
(image-dired--with-dired-buffer):
* lisp/image/image-dired-tags.el (image-dired--with-db-file)
(image-dired-remove-tag, image-dired-list-tags)
(image-dired-tag-files, image-dired-write-comments)
(image-dired-update-property):
* lisp/image/image-dired-external.el (image-dired-cmd-pngnq-options)
(image-dired-cmd-pngcrush-program)
(image-dired-cmd-pngcrush-options)
(image-dired-cmd-optipng-options)
(image-dired-cmd-create-standard-thumbnail-options)
(image-dired-cmd-rotate-original-program)
(image-dired-cmd-rotate-original-options)
(image-dired-cmd-write-exif-data-options, image-dired-queue)
(image-dired-queue-active-limit, image-dired-pngnq-thumb)
(image-dired-pngcrush-thumb, image-dired-optipng-thumb)
(image-dired-thumb-queue-run, image-dired-get-exif-file-name)
(image-dired-thumbnail-set-image-description):
* lisp/image/image-dired.el (image-dired-thumbnail-storage)
(image-dired-tags-db-file)
(image-dired-rotate-original-ask-before-overwrite)
(image-dired-line-up-method, image-dired-track-movement)
(image-dired-display-properties-format)
(image-dired-external-viewer)
(image-dired-show-all-from-dir-max-files)
(image-dired-insert-image)
(image-dired-dired-with-window-configuration)
(image-dired-restore-window-configuration)
(image-dired-track-original-file)
(image-dired-toggle-movement-tracking)
(image-dired-format-properties-string)
(image-dired--on-file-in-dired-buffer)
(image-dired-thumbnail-display-external)
(image-dired-display-image, image-dired-copy-filename-as-kill):
* lisp/image/image-dired-dired.el
(image-dired-dired-toggle-marked-thumbs)
(image-dired-dired-after-readin-hook)
(image-dired-next-line-and-display)
(image-dired-previous-line-and-display)
(image-dired-mark-and-display-next, image-dired-track-thumbnail)
(image-dired-dired-next-line, image-dired-dired-previous-line)
(image-dired-dired-display-external)
(image-dired-copy-with-exif-file-name)
(image-dired-mark-tagged-files)
(image-dired-dired-display-properties):
* lisp/image/image-crop.el (image-crop-exif-rotate)
(image-crop-resize-command, image-crop-cut-command)
(image-crop-crop-command, image-crop-rotate-command)
(image-crop-buffer-text-function, image-cut-color):
* lisp/image/image-converter.el (image-converter)
(image-convert-to-format, image-converter-regexp)
(image-converter--converters, image-convert-p, image-convert)
(image-converter--value, image-converter--probe)
(image-converter--find-converter, image-converter--convert)
(image-converter-add-handler):
* lisp/image/exif.el (exif-parse-buffer, exif-field)
(exif-orientation, exif--direct-ascii-value)
(exif--process-value, exif--read-chunk, exif--read-number-be)
(exif--read-number-le, exif--read-number): Fix doc strings.

1 files changed, 27 insertions, 20 deletions

diff --git a/lisp/image/exif.el b/lisp/image/exif.el
index c561ea729af..503e3ffadc7 100644
--- a/lisp/image/exif.el
+++ b/lisp/image/exif.el
@@ -110,7 +110,7 @@ from the return value of this function."
     (exif-parse-buffer)))
 
 (defun exif-parse-buffer (&optional buffer)
-  "Parse BUFFER (which should be a JPEG file) and return the Exif data, if any.
+  "Parse BUFFER (which should visit a JPEG file) and return Exif data, if any.
 The return value is a list of Exif items.
 
 If the data is invalid, an `exif-error' is signaled.
@@ -134,17 +134,17 @@ from the return value of this function."
           (exif--parse-exif-chunk app1))))))
 
 (defun exif-field (field data)
-  "Return raw FIELD from EXIF.
+  "Return raw FIELD from Exif DATA.
 If FIELD is not present in the data, return nil.
 FIELD is a symbol in the cdr of `exif-tag-alist'.
-DATA is the result of calling `exif-parse-file'."
+DATA is the result of calling `exif-parse-file' or `exif-parse-buffer'."
   (plist-get (seq-find (lambda (e)
                          (eq field (plist-get e :tag-name)))
                        data)
              :value))
 
 (defun exif-orientation (exif)
-  "Return the orientation (in degrees) in EXIF.
+  "Return the orientation (in degrees) in EXIF data.
 If the orientation isn't present in the data, return nil."
   (let ((code (exif-field 'orientation exif)))
     (cadr (assq code exif--orientation))))
@@ -254,21 +254,24 @@ If the orientation isn't present in the data, return nil."
         ;; We've reached the end of the directories.
         dir))))
 
-(defun exif--direct-ascii-value (value bytes le)
-  "Make VALUE into a zero-terminated string.
-VALUE is an integer representing BYTES characters."
+(defun exif--direct-ascii-value (value nbytes le)
+  "Make a string representing VALUE with NBYTES bytes according to LE endianness.
+VALUE is an integer value of NBYTES bytes.
+The return value is a null-terminated unibyte string whose length is
+NBYTES+1 bytes.  If LE is non-nil, the returned string representation of
+VALUE is little-endian, otherwise it is big-endian."
   (with-temp-buffer
     (set-buffer-multibyte nil)
     (if le
-        (dotimes (i bytes)
+        (dotimes (i nbytes)
           (insert (logand (ash value (* i -8)) 255)))
-      (dotimes (i bytes)
-        (insert (logand (ash value (* (- (1- bytes) i) -8)) 255))))
+      (dotimes (i nbytes)
+        (insert (logand (ash value (* (- (1- nbytes) i) -8)) 255))))
     (insert 0)
     (buffer-string)))
 
 (defun exif--process-value (value type le)
-  "Do type-based post-processing of the value."
+  "Do type-based post-processing of the VALUE whose endianness is per LE."
   (cl-case type
     ;; Chop off trailing zero byte.
     (ascii (substring value 0 (1- (length value))))
@@ -281,7 +284,8 @@ VALUE is an integer representing BYTES characters."
     (otherwise value)))
 
 (defun exif--read-chunk (bytes)
-  "Return BYTES octets from the buffer and advance point that much."
+  "Return BYTES octets from the current buffer and advance point that much.
+This function assumes that the current buffer is unibyte."
   (when (> (+ (point) bytes) (point-max))
     (signal 'exif-error "Premature end of file"))
   (prog1
@@ -289,8 +293,9 @@ VALUE is an integer representing BYTES characters."
     (forward-char bytes)))
 
 (defun exif--read-number-be (bytes)
-  "Read BYTES octets from the buffer as a chunk of big-endian bytes.
-Advance point to after the read bytes."
+  "Read BYTES octets from the current buffer as a chunk of big-endian bytes.
+Advance point to after the read bytes.
+This function assumes that the current buffer is unibyte."
   (when (> (+ (point) bytes) (point-max))
     (signal 'exif-error "Premature end of file"))
   (let ((sum 0))
@@ -300,8 +305,9 @@ Advance point to after the read bytes."
     sum))
 
 (defun exif--read-number-le (bytes)
-  "Read BYTES octets from the buffer as a chunk of low-endian bytes.
-Advance point to after the read bytes."
+  "Read BYTES octets from the current buffer as a chunk of little-endian bytes.
+Advance point to after the read bytes.
+This function assumes that the current buffer is unibyte."
   (when (> (+ (point) bytes) (point-max))
     (signal 'exif-error "Premature end of file"))
   (let ((sum 0))
@@ -310,10 +316,11 @@ Advance point to after the read bytes."
       (forward-char 1))
     sum))
 
-(defun exif--read-number (bytes lower-endian)
-  "Read BYTES octets from the buffer with endianness determined by LOWER-ENDIAN.
-Advance point to after the read bytes."
-  (if lower-endian
+(defun exif--read-number (bytes little-endian)
+  "Read BYTES octets from current buffer with endianness given by LITTLE-ENDIAN.
+Advance point to after the read bytes.
+This function assumes that the current buffer is unibyte."
+  (if little-endian
       (exif--read-number-le bytes)
     (exif--read-number-be bytes)))