branch: externals/org-contacts
commit 014881113601cb54c53adc155bc12afce6ce2e6d
Author: stardiviner <numbch...@gmail.com>
Commit: stardiviner <numbch...@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)))
