GNU bug report logs - #79168
30.1; Proposed changes for oauth2

Previous Next

Full log

View this message in rfc822 format

From: Xiyue Deng <manphiz <at> gmail.com>
To: 79168 <at> debbugs.gnu.org
Cc: Xiyue Deng <manphiz <at> gmail.com>
Subject: bug#79168: [PATCH 05/11] Documentation updates
Date: Fri,  8 Aug 2025 23:45:44 -0700

(Some adapted from bug#52746 by Aleksandr Vityazev.)
* packages/oauth2/oauth2.el: Update module commments to better reflect
its usage.  Also update function documentations.
---
 oauth2.el | 55 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 39 insertions(+), 16 deletions(-)

diff --git a/oauth2.el b/oauth2.el
index ef82a64c5f..ba7125e79b 100644
--- a/oauth2.el
+++ b/oauth2.el
@@ -27,12 +27,12 @@
 ;; Implementation of the OAuth 2.0 draft.
 ;;
 ;; The main entry point is `oauth2-auth-and-store' which will return a token
-;; structure.  This token structure can be then used with
-;; `oauth2-url-retrieve-synchronously' or `oauth2-url-retrieve' to retrieve
-;; any data that need OAuth authentication to be accessed.
+;; structure, which contains information needed for OAuth2 authentication,
+;; e.g. access_token, refresh_token, etc.
 ;;
-;; If the token needs to be refreshed, the code handles it automatically and
-;; store the new value of the access token.
+;; If the token needs to be refreshed, call `oauth2-refresh-access' on the token
+;; and it will be refreshed with a new access_token.  The code will also store
+;; the new value of the access token for reuse.
 
 ;;; Code:
 
@@ -72,8 +72,14 @@
 
 (defun oauth2-request-authorization (auth-url client-id &optional scope state redirect-uri)
   "Request OAuth authorization at AUTH-URL by launching `browse-url'.
-CLIENT-ID is the client id provided by the provider.
-It returns the code provided by the service."
+CLIENT-ID is the client id provided by the provider which uses
+REDIRECT-URI when requesting an access-token.  The default redirect_uri
+for desktop application is usually \"urn:ietf:wg:oauth:2.0:oob\".  SCOPE
+identifies the resources that your application can access on the user's
+behalf.  STATE is a string that your application uses to maintain the
+state between the request and redirect response.
+
+Returns the code provided by the service."
   (let ((url (concat auth-url
                      (if (string-match-p "\?" auth-url) "&" "?")
                      "client_id=" (url-hexify-string client-id)
@@ -97,7 +103,7 @@ It returns the code provided by the service."
     (json-read)))
 
 (defun oauth2-make-access-request (url data)
-  "Make an access request to URL using DATA in POST."
+  "Make an access request to URL using DATA in POST requests."
   (let ((func-name (nth 1 (backtrace-frame 2))))
     (oauth2--do-debug "%s: url: %s" func-name url)
     (oauth2--do-debug "%s: data: %s" func-name data)
@@ -122,9 +128,14 @@ It returns the code provided by the service."
   access-response)
 
 (defun oauth2-request-access (token-url client-id client-secret code &optional redirect-uri)
-  "Request OAuth access at TOKEN-URL.
-The CODE should be obtained with `oauth2-request-authorization'.
-Return an `oauth2-token' structure."
+  "Request OAuth access.
+TOKEN-URL is the URL for making the request.  CLIENT-ID and
+CLIENT-SECRET are provided by the service provider.  The CODE should be
+obtained with `oauth2-request-authorization'.  REDIRECT-URI is used when
+requesting access-token.  The default value for desktop application is
+usually \"urn:ietf:wg:oauth:2.0:oob\".
+
+Returns an `oauth2-token'."
   (when code
     (let ((result
            (oauth2-make-access-request
@@ -183,13 +194,21 @@ TOKEN should be obtained with `oauth2-request-access'."
    redirect-uri))
 
 (defun oauth2-compute-id (auth-url token-url scope client-id)
-  "Compute an unique id based on URLs.
+  "Compute an unique id based on AUTH-URL, TOKEN-URL, SCOPE, and CLIENT-ID.
 This allows to store the token in an unique way."
   (secure-hash 'sha512 (concat auth-url token-url scope client-id)))
 
 ;;;###autoload
 (defun oauth2-auth-and-store (auth-url token-url scope client-id client-secret &optional redirect-uri state)
-  "Request access to a resource and store it using `plstore'."
+  "Request access to a resource and store it.
+AUTH-URL and TOKEN-URL are provided by the service provider.  CLIENT-ID
+and CLIENT-SECRET should be generated by the service provider when a
+user registers an application.  SCOPE identifies the resources that your
+application can access on the user's behalf.  STATE is a string that
+your application uses to maintain the state between the request and
+redirect response.
+
+Returns an `oauth2-token'."
   ;; We store a MD5 sum of all URL
   (let* ((plstore (plstore-open oauth2-token-file))
          (id (oauth2-compute-id auth-url token-url scope client-id))
@@ -256,7 +275,9 @@ This allows to store the token in an unique way."
 ;;;###autoload
 (defun oauth2-url-retrieve-synchronously (token url &optional request-method request-data request-extra-headers)
   "Retrieve an URL synchronously using TOKEN to access it.
-TOKEN can be obtained with `oauth2-auth'."
+TOKEN can be obtained with `oauth2-auth'.  REQUEST-METHOD, REQUEST-DATA,
+and REQUEST-EXTRA-HEADERS are used when retrieving URL.  See also
+`url-retrieve-synchronously'."
   (let* ((oauth2--token-data (cons token url)))
     (let ((oauth2--url-advice t)         ;Activate our advice.
           (url-request-method request-method)
@@ -270,8 +291,10 @@ TOKEN can be obtained with `oauth2-auth'."
                                   cbargs
                                   request-method request-data request-extra-headers)
   "Retrieve an URL asynchronously using TOKEN to access it.
-TOKEN can be obtained with `oauth2-auth'.  CALLBACK gets called with CBARGS
-when finished.  See `url-retrieve'."
+TOKEN can be obtained with `oauth2-auth'.  CALLBACK gets called with
+CBARGS when finished. TOKEN can be obtained with `oauth2-auth'.
+REQUEST-METHOD, REQUEST-DATA, and REQUEST-EXTRA-HEADERS are used when
+retrieving URL.  See also `url-retrieve'."
   ;; TODO add support for SILENT and INHIBIT-COOKIES.  How to handle this in `url-http-handle-authentication'.
   (let* ((oauth2--token-data (cons token url)))
     (let ((oauth2--url-advice t)         ;Activate our advice.
-- 
2.39.5

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.