[elpa] externals/org-contacts 0148811136 2/3: fix flymake warnings in docstrings

[ELPA Syncer]

branch: externals/org-contacts
commit 014881113601cb54c53adc155bc12afce6ce2e6d
Author: stardiviner <numbchild@gmail.com>
Commit: stardiviner <numbchild@gmail.com>

    fix flymake warnings in docstrings
---
 org-contacts.el | 72 +++++++++++++++++++++++++++------------------------------
 1 file changed, 34 insertions(+), 38 deletions(-)

diff --git a/org-contacts.el b/org-contacts.el
index 8051171b9d..3b1d3e055c 100644
--- a/org-contacts.el
+++ b/org-contacts.el
@@ -118,11 +118,9 @@ When set to nil, all your Org files will be used."
   :type 'string)
 
 (defcustom org-contacts-ignore-property "IGNORE"
-  "Name of the property, which values will be ignored when
-completing or exporting to vcard."
+  "Name of the property which values ignored when completing or exporting to 
vCard."
   :type 'string)
 
-
 (defcustom org-contacts-birthday-format "Birthday: %l (%Y)"
   "Format of the anniversary agenda entry.
 The following replacements are available:
@@ -305,8 +303,7 @@ buffer."
     org-contacts-db))
 
 (defun org-contacts-at-point (&optional pom)
-  "Return the contacts at point-or-marker POM or current position
-if nil."
+  "Return the contacts at point or marker POM or current position."
   (setq pom (or pom (point)))
   (org-with-point-at pom
     (list (org-get-heading t) (set-marker (make-marker) pom) 
(org-entry-properties pom 'all))))
@@ -316,8 +313,7 @@ if nil."
 If all match values are nil, return all contacts.
 
 The optional PROP-MATCH argument is a single (PROP . VALUE) cons
-cell corresponding to the contact properties.
-"
+cell corresponding to the contact properties."
   (if (and (null name-match)
            (null prop-match)
            (null tags-match))
@@ -466,7 +462,7 @@ prefixes rather than just the beginning of the string."
                )))))
 
 (defun org-contacts-display-sort-function (completions)
-  "Sort function for contacts display."
+  "Sort function for contacts COMPLETIONS."
   (mapcar (lambda (string)
             (cl-loop with len = (1- (length string))
                      for i upfrom 0 to len
@@ -500,7 +496,7 @@ prefixes rather than just the beginning of the string."
               (display-sort-function . org-contacts-display-sort-function))))
 
 (defun org-contacts-complete-group (string)
-  "Complete text at START from a group.
+  "Complete STRING as start from a group.
 
 A group FOO is composed of contacts with the tag FOO."
   (let* ((completion-ignore-case org-contacts-completion-ignore-case)
@@ -544,13 +540,10 @@ A group FOO is composed of contacts with the tag FOO."
                                       (not 
org-contacts-completion-ignore-case)))))))
 
 (defun org-contacts-complete-tags-props (string)
-  "Insert emails that match the tags expression.
-
-For example: FOO-BAR will match entries tagged with FOO but not
-with BAR.
+  "Insert emails that match the tags expression beginning with STRING.
 
-See (org) Matching tags and properties for a complete
-description."
+For example: FOO-BAR will match entries tagged with FOO but not with BAR.
+See (org) Matching tags and properties for a complete description."
   (let* ((completion-ignore-case org-contacts-completion-ignore-case)
          (completion-p (string-match-p
                         (concat "^" org-contacts-tags-props-prefix) string)))
@@ -586,8 +579,7 @@ description."
           result)))))
 
 (defun org-contacts-remove-ignored-property-values (ignore-list list)
-  "Remove all ignore-list's elements from list and you can use
-   regular expressions in the ignore list."
+  "Remove all IGNORE-LIST's elements from LIST and you can use regular 
expressions in the ignore list."
   (cl-remove-if (lambda (el)
                   (cl-find-if (lambda (x)
                                 (string-match-p x el))
@@ -595,7 +587,7 @@ description."
                 list))
 
 (defun org-contacts-complete-name (string)
-  "Complete text at START with a user name and email."
+  "Complete STRING at start with a user name and email."
   (let* ((completion-ignore-case org-contacts-completion-ignore-case)
          (completion-list
           (cl-loop for contact in (org-contacts-filter)
@@ -646,12 +638,12 @@ description."
                   'org-contacts-complete-functions string))))))))
 
 (defun org-contacts-org-complete--annotation-function (candidate)
-  "Return org-contacts tags of contact candidate."
+  "Return `org-contacts' tags of contact CANDIDATE."
   ;; TODO
   (ignore candidate))
 
 (defun org-contacts-org-complete--doc-function (candidate)
-  "Return org-contacts content of contact candidate."
+  "Return `org-contacts' content of contact CANDIDATE."
   (let* ((candidate (substring-no-properties candidate 1 nil))
          (contact (seq-find
                    (lambda (contact) (string-equal (plist-get contact :name) 
candidate))
@@ -689,7 +681,7 @@ description."
 (add-to-list 'display-buffer-alist '("^ \\*org-contact\\*" . 
(display-buffer-below-selected)))
 
 (defun org-contacts-org-complete--location-function (candidate)
-  "Return org-contacts location of contact candidate."
+  "Return `org-contacts' location of contact CANDIDATE."
   (let* ((candidate (substring-no-properties candidate 1 nil))
          (contact (seq-find
                    (lambda (contact) (string-equal (plist-get contact :name) 
candidate))
@@ -704,7 +696,7 @@ description."
 
 ;;;###autoload
 (defun org-contacts-org-complete-function ()
-  "completion-at-point function to complete @name in `org-mode'.
+  "`completion-at-point' function to complete @name in `org-mode'.
 Usage: (add-hook \\='completion-at-point-functions
                  #\\='org-contacts-org-complete-function nil \\='local)"
   (when-let* ((end (point))
@@ -863,7 +855,9 @@ This function should be called from 
`gnus-article-prepare-hook'."
     ,org-contacts-address-property
     ,org-contacts-birthday-property)
   "Matching rule for finding heading that are contacts.
-This can be property key checking.")
+This can be property key checking."
+  :type 'list
+  :safe 'listp)
 
 (defvar org-contacts-ahead-space-padding (make-string 5 ? )
   "The space padding for align avatar image with contact name and properties.")
@@ -944,13 +938,13 @@ This can be property key checking.")
           (get-text-property 0 'annotation candidate)))
 
 (defun org-contacts--return-candidates (&optional files)
-  "Return org-contacts candidates which parsed from FILES."
+  "Return `org-contacts' candidates which parsed from FILES."
   (if-let ((files (or files org-contacts-files)))
       (org-contacts--candidates files)
     (user-error "Files does not exist: %S" files)))
 
 (defvar org-contacts--candidates-cache nil
-  "A cache variable of org-contacts--candidates.")
+  "A cache variable of `org-contacts--candidates'.")
 
 (defun org-contacts-browse-function (contact-name)
   "Jump to CONTACT-NAME headline."
@@ -968,7 +962,7 @@ This can be property key checking.")
 
 ;;;###autoload
 (defun org-contacts (&optional files)
-  "Search org-contacts from FILES and jump to contact location."
+  "Search `org-contacts' from FILES and jump to contact location."
   (interactive)
   (unless org-contacts--candidates-cache
     (setq org-contacts--candidates-cache
@@ -1311,7 +1305,7 @@ to do our best."
      "END:VCARD\n\n")))
 
 (defun org-contacts-export-as-vcard (&optional name file to-buffer)
-  "Export org contacts to V-Card 3.0.
+  "Export org-contacts to V-Card 3.0.
 
 By default, all contacts are exported to `org-contacts-vcard-file'.
 
@@ -1362,10 +1356,10 @@ is created and the VCard is written into that buffer."
 
 (defun org-contacts-show-map (&optional name)
   "Show contacts on a map.
-Requires google-maps-el."
+Requires google-maps.el."
   (interactive)
   (unless (fboundp 'google-maps-static-show)
-    (error "`org-contacts-show-map' requires `google-maps-el'"))
+    (error "`org-contacts-show-map' requires `google-maps.el'"))
   (google-maps-static-show
    :markers
    (cl-loop
@@ -1375,8 +1369,10 @@ Requires google-maps-el."
     collect (cons (list addr) (list :label (string-to-char (car contact)))))))
 
 (defun org-contacts-strip-link (link)
-  "Remove brackets, description, link type and colon from an org
-link string and return the pure link target."
+  "Strip Org LINK extra delimiters.
+
+Remove brackets, description, link type and colon from an Org link
+string and return the pure link target."
   (let (startpos colonpos endpos)
     (setq startpos (string-match (regexp-opt '("[[tel:" "[[mailto:";)) link))
     (if startpos
@@ -1505,7 +1501,7 @@ Each element has the form (NAME . (FILE . POSITION))."
 
 ;;;###autoload
 (defun org-contacts-link-open (query)
-  "Open contacts: link type with jumping or searching."
+  "Open org-contacts: link with jumping or searching QUERY."
   (let* ((file-path (car (org-contacts-files)))
          (file-name (file-name-nondirectory file-path))
          (buf (or (get-buffer file-name) (get-buffer (find-file-noselect 
file-path)))))
@@ -1523,7 +1519,7 @@ Each element has the form (NAME . (FILE . POSITION))."
             (progn
               (goto-char (marker-position position))
               (org-fold-show-context))
-          (user-error "[org-contacts] Can't find <%s> in your 
`org-contacts-files'." query)))
+          (user-error "[org-contacts] Can't find <%s> in your 
`org-contacts-files'" query)))
       (display-buffer buf '(display-buffer-below-selected))
 
       ;; FIXME:
@@ -1542,7 +1538,7 @@ Each element has the form (NAME . (FILE . POSITION))."
 
 ;;;###autoload
 (defun org-contacts-link-complete (&optional _arg)
-  "Create a org-contacts link using completion."
+  "Create a `org-contacts' link using completion."
   (let ((name (completing-read "org-contacts NAME: "
                                (mapcar
                                 (lambda (plist) (plist-get plist :name))
@@ -1550,7 +1546,7 @@ Each element has the form (NAME . (FILE . POSITION))."
     (concat "org-contact:" name)))
 
 (defun org-contacts-link-face (path)
-  "Different face color for different org-contacts link query."
+  "Different face color for different org-contacts: link PATH."
   (cond
    ((string-match "/.*/" path)
     '(:background "sky blue" :overline t :slant 'italic))
@@ -1564,10 +1560,10 @@ Each element has the form (NAME . (FILE . POSITION))."
       (org-add-link-type "mailto")))
 
 (defvar org-contacts-emails-list nil
-  "A list variable of all org-contacts emails.")
+  "A list variable of all `org-contacts' emails.")
 
 (defun org-contacts-mailto-link--get-all-emails ()
-  "Retrieve all org-contacts EMAIL property values."
+  "Retrieve all `org-contacts' EMAIL property values."
   (setq org-contacts-emails-list
         (mapcar
          (lambda (contact)
@@ -1595,7 +1591,7 @@ Each element has the form (NAME . (FILE . POSITION))."
           (delete nil org-contacts-emails-list)))
 
 (defun org-contacts-mailto-link-completion (&optional _arg)
-  "Org mode link `mailto:' completion with org-contacts emails."
+  "Org mode link `mailto:' completion with `org-contacts' emails."
   (let ((email (completing-read "org-contacts EMAIL: "
                                 (org-contacts-mailto-link--get-all-emails))))
     (concat "mailto:"; email)))