update docstrings

Author: sav

pushbullet-api.el

@@ -41,43 +41,39 @@
 
 (defcustom pushbullet-api-token nil
   "Your personal Pushbullet API access token.
-This token is required for authentication with the Pushbullet API. You
-can obtain your access token from the Pushbullet account settings page:
+This token is required for authentication with the Pushbullet API.
+You can obtain your access token from the Pushbullet account settings page:
 `https://www.pushbullet.com/#settings/account`."
   :type 'string
   :group 'pushbullet-api)
 
 (defcustom pushbullet-api-limit 20
-  "The maximum number of pushes to fetch in a single API request for
- pagination."
+  "The maximum number of pushes to fetch in a single API request for pagination."
   :type 'integer
   :group 'pushbullet-api)
 
 (defcustom pushbullet-api-debug nil
-   "Enable verbose logging for Pushbullet API operations.
+  "Enable verbose logging for Pushbullet API operations.
 When non-nil, additional debug messages will be printed to the *Messages* buffer."
-   :type 'boolean
-   :group 'pushbullet-api)
+  :type 'boolean
+  :group 'pushbullet-api)
 
 (defvar pushbullet-api-url "https://api.pushbullet.com/v2"
-   "The base URL for all Pushbullet API v2 endpoints.")
+  "The base URL for all Pushbullet API v2 endpoints.")
 
 (defvar-local pushbullet-api-cursor nil
-   "A buffer-local string used for pagination in Pushbullet API requests,
- indicating the point from which to fetch subsequent pushes.")
+  "A buffer-local string used for pagination in Pushbullet API requests, indicating the point from which to fetch subsequent pushes.")
 
 (defmacro pushbullet-api--log (fmt &rest args)
-  "Log a debug message with FMT and ARGS when `pushbullet-debug' is
- enabled.
-The message is prefixed with '[pushbullet]' for identification."
+  "Logs a debug message with FMT and ARGS when `pushbullet-api-debug' is enabled.
+The message is prefixed with '[pushbullet-api]' for identification."
   `(when pushbullet-api-debug
      (message (concat "[pushbullet-api] " ,fmt) ,@args)))
 
 (defun pushbullet-api--check-token ()
-  "Ensures that the `pushbullet-api-token' is set, either directly or by
- retrieving it from `auth-source'.
-If the token is not found, an error is signaled prompting the user to
-set it."
+  "Ensures that `pushbullet-api-token' is set, either directly or by
+retrieving it from `auth-source'.
+If the token is not found, an error is signaled, prompting the user to set it."
   pushbullet-api-token
   (unless pushbullet-api-token
     (let ((auth-source-token (auth-source-pick-first-password :host "pushbullet.com")))
@@ -90,13 +86,12 @@ set it."
   "Makes an asynchronous HTTP request to the Pushbullet API.
 
 METHOD is a string representing the HTTP method (e.g., 'GET', 'POST', 'DELETE').
-ENDPOINT is a string specifying the API endpoint relative to `pushbullet-api-url`.
+ENDPOINT is a string specifying the API endpoint relative to `pushbullet-api-url'.
 DATA is an optional alist of request data to be sent as JSON.
-CALLBACK is a function to be called upon successful API response, receiving the parsed JSON data.
+CALLBACK is a function to be called upon a successful API response, receiving the parsed JSON data.
 ERROR-CALLBACK is an optional function to be called if the API request encounters an error.
 
-This function automatically includes the `pushbullet-api-token' for
-authentication and handles JSON encoding/decoding."
+This function automatically includes `pushbullet-api-token' for authentication and handles JSON encoding/decoding."
   (pushbullet-api--check-token)
   (let ((url (concat pushbullet-api-url endpoint))
         (headers `(("Access-Token" . ,pushbullet-api-token)
@@ -114,19 +109,18 @@ authentication and handles JSON encoding/decoding."
 
 (defun pushbullet-api--fetch-url (&optional limit)
   "Constructs the API endpoint for fetching pushes, incorporating
- `CURSOR' for pagination.
-If CURSOR is `nil', it fetches the initial set of pushes. Otherwise, it
-fetches subsequent pushes using the provided CURSOR value and
-`pushbullet-api-limit`.
-Then the optional argument LIMIT is provided, fetch at most LIMIT items."
+`pushbullet-api-cursor' for pagination.
+If `pushbullet-api-cursor' is `nil', it fetches the initial set of pushes.
+Otherwise, it fetches subsequent pushes using the provided
+`pushbullet-api-cursor' value and `pushbullet-api-limit'.
+If the optional argument LIMIT is provided, it fetches at most LIMIT items."
   (let* ((n (or limit pushbullet-api-limit)))
     (if pushbullet-api-cursor
         (format "/pushes?limit=%d&cursor=%s" n pushbullet-api-cursor)
       (format "/pushes?limit=%d" n))))
 
 (defun pushbullet-api-active (push)
-  "Returns true if PUSH has data and should be displayed. Returns `nil'
- otherwise."
+  "Returns true if PUSH has data and should be displayed; otherwise, returns `nil`."
   (let* ((active (alist-get 'active push))
          (title (alist-get 'title push))
          (url (alist-get 'url push))
@@ -138,11 +132,10 @@ Then the optional argument LIMIT is provided, fetch at most LIMIT items."
 
 (defun pushbullet-api-fetch (callback &optional limit)
   "Fetches Pushbullet pushes from the API.
-It uses `pushbullet-api-cursor' for pagination to fetch subsequent sets of
-pushes. Upon successful retrieval, the fetched pushes are filtered,
-`pushbullet-api-cursor' is updated, and CALLBACK is invoked with the
-filtered pushes. When optional argument LIIMIT is provided, fetch at
-most LIMIT items."
+It uses `pushbullet-api-cursor' for pagination to fetch subsequent sets of pushes.
+Upon successful retrieval, the fetched pushes are filtered,
+`pushbullet-api-cursor' is updated, and CALLBACK is invoked with the filtered pushes.
+If the optional argument LIMIT is provided, fetches at most LIMIT items."
   (pushbullet-api-request
    "GET" (pushbullet-api--fetch-url limit) nil
    (cl-function
@@ -154,10 +147,8 @@ most LIMIT items."
         (funcall callback (cl-coerce pushes 'list)))))))
 
 (defun pushbullet-api-delete (push)
-  "Deletes the specified PUSH (an alist containing at least an 'iden
- field) from the Pushbullet server.
-Upon successful deletion, a debug message is logged, and the Pushbullet
-UI is implicitly refreshed by `pushbullet` being called."
+  "Deletes the specified PUSH (an alist containing at least an 'iden field) from the Pushbullet server.
+Upon successful deletion, a debug message is logged, and the Pushbullet UI is implicitly refreshed by `pushbullet` being called."
   (let ((id (alist-get 'iden push)))
     (pushbullet-api-request
      "DELETE" (format "/pushes/%s" id) nil
@@ -166,6 +157,12 @@ UI is implicitly refreshed by `pushbullet` being called."
         (pushbullet-api--log "Push deleted: %S" push))))))
 
 (defun pushbullet-api-send (title body &optional url)
+  "Sends a push to the Pushbullet API.
+
+TITLE is a string specifying the title of the push.
+BODY is a string specifying the main content of the push.
+URL is an optional string specifying a URL to be included, transforming
+the push into a link."
   (let ((push `((type . ,"note")
                 (title . ,title)
                 (body . ,body))))

pushbullet.el

@@ -64,20 +64,16 @@
 When non-nil, additional debug messages will be printed to the
 *Messages* buffer."
   :type 'boolean
-  :group 'pushbullet
-  :initialize 'custom-initialize-default)
+  :group 'pushbullet)
 
 (defvar pushbullet-buffer-name "*Pushbullet*"
-  "The name of the main buffer where the Pushbullet user interface is
- displayed.")
+  "The name of the main buffer where the Pushbullet user interface is displayed.")
 
 (defvar pushbullet-export-buffer-name "*Pushbullet Export*"
-   "The name of the buffer used for exporting Pushbullet pushes to
- Org-mode format.")
+  "The name of the buffer used for exporting Pushbullet pushes to Org-mode format.")
 
 (defcustom pushbullet-default-title (format "GNU Emacs %s" emacs-version)
-  "The default title string used for new pushes when no explicit title
- is provided.
+  "The default title string used for new pushes when no explicit title is provided.
 It is formatted to include the current Emacs version."
   :type 'string
   :group 'pushbullet)
@@ -88,75 +84,68 @@ It is formatted to include the current Emacs version."
   :group 'pushbullet)
 
 (defcustom pushbullet-left-alignment 8
-   "The size of the left alignment padding in the Pushbullet UI."
-   :type 'integer
-   :group 'pushbullet)
+  "The size of the left alignment padding in the Pushbullet UI."
+  :type 'integer
+  :group 'pushbullet)
 
 (defcustom pushbullet-textfield-width
-   (truncate
-       (* (- pushbullet-columns pushbullet-left-alignment) 0.90))
-   "The calculated width for editable text fields within the Pushbullet UI."
-   :type 'integer
-   :group 'pushbullet)
+  (truncate
+   (* (- pushbullet-columns pushbullet-left-alignment) 0.90))
+  "The calculated width for editable text fields within the Pushbullet UI."
+  :type 'integer
+  :group 'pushbullet)
 
 (defcustom pushbullet-show-send-form t
   "Whether to display the send form in the Pushbullet UI."
   :type 'boolean
   :group 'pushbullet)
 
 (defvar pushbullet--buffer nil
-   "The buffer currently used for rendering the Pushbullet UI. This is a
- buffer-local variable.")
+  "The buffer currently used for rendering the Pushbullet UI. This is a buffer-local variable.")
 
 (defvar pushbullet--title nil
-   "The title string displayed at the top of the Pushbullet UI buffer.
- This is a buffer-local variable.")
+  "The title string displayed at the top of the Pushbullet UI buffer. This is a buffer-local variable.")
 
 (defvar pushbullet--pushes nil
-   "A buffer-local list of Pushbullet pushes currently displayed in the
- UI, where each push is an alist.")
+  "A buffer-local list of Pushbullet pushes currently displayed in the UI, where each push is an alist.")
 
 (defmacro pushbullet--log (fmt &rest args)
-  "Logs a debug message with FMT and ARGS if `pushbullet-debug' is
- enabled.
-The message is prefixed with '[pushbullet]' for easy identification
-in the `*Messages*' buffer."
+  "Logs a debug message with FMT and ARGS if `pushbullet-debug' is enabled.
+The message is prefixed with '[pushbullet]' for easy identification in the `*Messages*' buffer."
   `(when pushbullet-debug
      (message (concat "[pushbullet] " ,fmt) ,@args)))
 
 (defun pushbullet--align-right (max str)
-   "Inserts spaces to right-align STR within a field of MAX width in the
- current buffer."
-   (let ((len (length str)))
-       (when (>= max len)
-         (widget-insert (make-string (- max (length str)) ?\s)))))
+  "Inserts spaces to right-align STR within a field of MAX width in the current buffer."
+  (let ((len (length str)))
+    (when (>= max len)
+      (widget-insert (make-string (- max (length str)) ?\s)))))
 
 (defun pushbullet--insert-aligned (str)
-   "Inserts a newline and then the string STR, right-aligned by
- `pushbullet-left-alignment'."
-   (widget-insert "\n")
-   (pushbullet--align-right pushbullet-left-alignment str)
-   (widget-insert str))
+  "Inserts a newline and then the string STR, right-aligned by `pushbullet-left-alignment`."
+  (widget-insert "\n")
+  (pushbullet--align-right pushbullet-left-alignment str)
+  (widget-insert str))
 
 (defun pushbullet--list-filter (pushes)
-  "Filters a list of PUSHES, returning only those that are active and
- have at least a title, URL, or body."
+  "Filters a list of PUSHES, returning only those that are active and have at least a title, URL, or body."
   (seq-filter (lambda (push) (pushbullet-api-active push)) pushes))
 
 (defun pushbullet--list-remove (pushes push)
-  "Removes PUSH from LIST where elements in LIST match PUSH
- based on the `'iden' key-value pairs."
+  "Removes PUSH from PUSHES where elements in PUSHES match PUSH based on the `'iden' key-value pairs."
   (let ((iden (alist-get 'iden push)))
     (seq-remove (lambda (item) (equal (alist-get 'iden item) iden)) pushes)))
 
 (defun pushbullet--send (title body url)
+  "Sends a push with TITLE, BODY, and URL, then reloads the UI."
   (pushbullet-api-send title body url)
   (pushbullet--log "Pushed: (%S, %S, %S)" title body url)
   (pushbullet--load-more 1))
 
 (defun pushbullet--load-more (&optional limit)
-  "Fetches additional pushes from the Pushbullet server using the `fetch'
- callback from `pushbullet--api', and then re-renders the UI."
+  "Fetches additional pushes from the Pushbullet server using the
+ `pushbullet-api-fetch' function, then re-renders the UI.
+If LIMIT is provided, fetches at most LIMIT pushes."
   (let ((fetch (alist-get 'fetch pushbullet--api)))
     (pushbullet-api-fetch
      #'(lambda (pushes)
@@ -175,23 +164,21 @@ in the `*Messages*' buffer."
   nil)
 
 (defun pushbullet--export-all ()
-  "Exports all currently loaded pushes to an Org-mode buffer using the
- `export' callback from `pushbullet--api'."
+  "Exports all currently loaded pushes to an Org-mode buffer using
+ `pushbullet-export'."
   (pushbullet-export pushbullet--pushes))
 
 (defun pushbullet--delete-all (&rest args)
   "Deletes all pushes currently displayed in the UI from the Pushbullet
- server using the `delete' callback from `pushbullet--api', then
- re-renders the UI."
+ server using `pushbullet-api-delete', then re-renders the UI."
   (dolist (push pushbullet--pushes)
     (pushbullet-api-delete push))
   (setq pushbullet--pushes nil)
   (pushbullet--render))
 
 (defun pushbullet--delete-row (push)
-  "Deletes a single PUSH from the `pushbullet--pushes' list, invokes
- the `delete' callback from `pushbullet--api', and then re-renders
- the UI."
+  "Deletes a single PUSH from `pushbullet--pushes', invokes
+ `pushbullet-api-delete', and then re-renders the UI."
   (setq pushbullet--pushes
         (pushbullet--list-remove pushbullet--pushes push))
   (pushbullet-api-delete push)
@@ -255,16 +242,15 @@ title, URL, and body, and 'Delete' buttons."
     (widget-insert "\n")))
 
 (defun pushbullet--render-pushes ()
-  "Render the list of pushes in the UI (`pushbullet-ai--pushes')."
+  "Renders the list of pushes in the UI (`pushbullet--pushes')."
   (dolist (push pushbullet--pushes)
     (when (pushbullet-api-active push)
       (pushbullet--render-push push))))
 
 (defun pushbullet--render-form ()
   "Renders the 'New Push' form, allowing users to input a title, URL,
  and body for a new Pushbullet push.
-Includes a 'Push' button to submit the form via the `send' callback from
-`pushbullet--api'."
+Includes a 'Push' button to submit the form via `pushbullet--send'."
   (widget-insert
    (propertize
     (concat "\n\n\n══ New Push "
@@ -357,12 +343,12 @@ Each active push is formatted as an Org-mode heading, including its
 title, URL (if present), and body.
 
 If PUSHES is `nil` or the function is called interactively, it exports
-the currently displayed pushes from the UI (`pushbullet-ui--pushes`).
+the currently displayed pushes from the UI (`pushbullet--pushes').
 
 This function is interactive."
   (interactive)
   (let ((buffer (get-buffer-create pushbullet-export-buffer-name))
-    	(pushes (or pushes pushbullet-ui--pushes)))
+    	(pushes (or pushes pushbullet--pushes)))
     (with-current-buffer buffer
       (remove-overlays)
       (erase-buffer)