summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKyle Meyer <kyle@kyleam.com>2014-11-22 03:04:55 -0500
committerKyle Meyer <kyle@kyleam.com>2014-11-22 03:04:55 -0500
commitf78eeb3da3a92c7c4a35dfc0f567ecb1f8d3c016 (patch)
treefaee156b07a16e875535513be67cbf680b5ea3c6
parent34bc37c49135d818804e22106b947d5e4de699e7 (diff)
downloadbog-f78eeb3da3a92c7c4a35dfc0f567ecb1f8d3c016.tar.gz
Add some missing docstrings
-rw-r--r--bog.el19
1 files changed, 19 insertions, 0 deletions
diff --git a/bog.el b/bog.el
index af24c0c..ab66a30 100644
--- a/bog.el
+++ b/bog.el
@@ -266,20 +266,24 @@ be preceded by a characters in `bog-allowed-before-citekey'."
(bog-citekey-from-property)))
(defun bog-citekey-from-heading-title ()
+ "Retrieve citekey from heading title."
(unless (org-before-first-heading-p)
(let ((heading (org-no-properties (org-get-heading t t))))
(when (bog-citekey-p heading) heading))))
(defun bog-citekey-from-property ()
+ "Retrieve citekey from `bog-citekey-property'."
(--when-let (org-entry-get (point) bog-citekey-property)
(when (bog-citekey-p it) it)))
(defun bog-citekey-p (text)
+ "Does TEXT match `bog-citekey-format'?"
(when (string-match-p (format "^%s$" bog-citekey-format) text)
t))
(defvar bog--all-citekeys nil)
(defun bog-all-citekeys ()
+ "Return all citekeys in `bog-notes-files'."
(or (and bog-use-citekey-cache bog--all-citekeys)
(setq bog--all-citekeys (apply 'append
(-map 'bog-citekeys-in-file
@@ -287,16 +291,19 @@ be preceded by a characters in `bog-allowed-before-citekey'."
(defvar bog--all-heading-citekeys nil)
(defun bog-all-heading-citekeys ()
+ "Return all citekeys in headings of `bog-notes-files'."
(or (and bog-use-citekey-cache bog--all-heading-citekeys)
(setq bog--all-heading-citekeys (-mapcat 'bog-heading-citekeys-in-file
(bog-notes-files)))))
(defun bog-clear-citekey-cache ()
+ "Clear cache of citekeys contained in `bog-notes-files'."
(interactive)
(setq bog--all-citekeys nil
bog--all-heading-citekeys nil))
(defun bog-citekeys-in-file (file)
+ "Return all citekeys in FILE."
(let (refs)
(with-temp-buffer
(org-mode)
@@ -306,16 +313,19 @@ be preceded by a characters in `bog-allowed-before-citekey'."
(-distinct refs)))
(defun bog-heading-citekeys-in-file (file)
+ "Return all citekeys in headings of FILE."
(with-temp-buffer
(org-mode)
(insert-file-contents file)
(setq citekeys (bog-heading-citekeys-in-buffer))))
(defun bog-heading-citekeys-in-buffer ()
+ "Return all citekeys in current buffer."
(--keep it
(org-map-entries 'bog-citekey-from-heading)))
(defun bog-heading-citekeys-in-wide-buffer ()
+ "Return all citekeys in current buffer, without any narrowing."
(--keep it
(org-map-entries 'bog-citekey-from-heading nil 'file)))
@@ -350,6 +360,9 @@ opened if locating a citekey from context fails."
(org-open-file citekey-file)))
(defun bog-citekey-files (citekey)
+ "Return files in `bog-file-directory' associated with CITEKEY.
+These should be named CITEKEY<sep>*.<ext>, where <sep> is a
+character in `bog-citekey-file-name-separators'."
(let* ((patterns (--map (concat it "*") bog-citekey-file-name-separators))
(patterns (cons ".*" patterns)))
(--mapcat (file-expand-wildcards
@@ -413,6 +426,7 @@ used to control the default string used in the prompt."
citekey-file))
(defun bog-citekey-as-file (citekey ext)
+ "Return file name `bog-file-directory'/CITEKEY.<ext>."
(expand-file-name (concat citekey "." ext) bog-file-directory))
(defun bog-all-file-citekeys ()
@@ -420,16 +434,19 @@ used to control the default string used in the prompt."
(-distinct (-keep 'bog-file-citekey (bog-all-citekey-files))))
(defun bog-file-citekey (file)
+ "Return leading citekey part from base name of FILE."
(let ((fname (file-name-base file)))
(when (string-match (concat "^" bog-citekey-format) fname)
(match-string 0 fname))))
(defun bog-all-citekey-files ()
+ "Return list of all files in `bog-file-directory'."
(-remove 'file-directory-p
(directory-files bog-file-directory
t directory-files-no-dot-files-regexp)))
(defun bog-staged-files ()
+ "Return files in `bog-stage-directory'."
(-remove 'file-directory-p
(directory-files bog-stage-directory
t directory-files-no-dot-files-regexp)))
@@ -531,6 +548,7 @@ alphabetically."
refs)))
(defun bog-citekey-as-bib (citekey)
+ "Return file name `bog-bib-directory'/CITEKEY.bib."
(expand-file-name (concat citekey ".bib") bog-bib-directory))
(defun bog-bib-citekeys ()
@@ -677,6 +695,7 @@ level `bog-refile-maxlevel' are considered."
(org-refile)))
(defun bog-notes-files ()
+ "Return Org files in `bog-notes-files'."
(file-expand-wildcards
(concat (file-name-as-directory bog-notes-directory)
"*.org")))