README tweaks

README.org

@@ -225,15 +225,15 @@ You can save this history across sessions by adding =citar-history= to =savehist
 
 Citar uses a cache to speed up library display.
 If a bib file changes, the cache will automatically update the next time you run a Citar command.
-
-The =citar-cache-refresh= command will also reload the caches manually.
+Note that cached data preformatted completion candidates are independently tracked by file.
+So, for example, if you have one very large bibliography file that changes a lot, you might consider splitting into one large file that is more stable, and one-or-more smaller ones that change more frequently.
 
 ** Notes
 
 Citar offers configurable note-taking and access integration.
 The ~citar-notes-sources~ variable configures note backends, and ~citar-notes-source~ activates your chosen backend.
 A backend primarily specifies functions to update the Citar display, to create the completion candidates, and to open existing and new notes.
-See the docstrings for details.
+See the ~citar-notes-sources~ docstring for details, and the =citar-register-note-source= and =citar-remove-note-source= convenience functions.
 
 ** Files, file association and file-field parsing
 

citar-file.el

@@ -331,6 +331,7 @@ need to scan the contents of DIRS in this case."
 
 (defun citar-file-has-notes (&optional _entries)
   "Return predicate testing whether cite key has associated notes."
+  ;; REVIEW why this optional arg when not needed?
   (let ((files (citar-file--get-notes-hash)))
     (lambda (key)
       (gethash key files))))

citar.el

@@ -513,8 +513,8 @@ FILTER: if non-nil, should be a predicate function taking
 (cl-defun citar-select-ref (&key filter)
   "Select bibliographic references.
 
-Call `citar-select-ref' with argument `:multiple'; see its
-documentation for the return value."
+Call 'citar-select-ref' with argument ':multiple, and optional
+FILTER; see its documentation for the return value."
   (car (citar-select-refs :multiple nil :filter filter)))
 
 (defun citar--multiple-completion-table (selected-hash candidates filter)
@@ -632,7 +632,6 @@ Optionally constrain to FILES, NOTES, and/or LINKS."
       (completing-read
        "Select resource: "
        (lambda (string predicate action)
-         ;; REVIEW how to hook in annotation functions here by category?
          (if (eq action 'metadata)
              `(metadata
                (group-function . citar--select-group-related-resources)