minor doc fixes

[squeep-indieauth-helper] / lib / communication.js

diff --git a/lib/communication.js b/lib/communication.js
index 18a6e588070e39bb49790433885189703a3bc5d0..d160707ee3bb157559bf594da2f16d12cfcf0db3 100644 (file)
--- a/lib/communication.js
+++ b/lib/communication.js
@@ -399,6 +399,7 @@ class Communication {
    * N.B. Sets isLoopback on urlObj
    * @param {URL} urlObj
    * @param {Boolean} allowLoopback
+   * @param {Boolean} resolveHostname
    * @returns {Promise<void>}
    */
   static async _urlNamedHost(urlObj, allowLoopback, resolveHostname) {
@@ -488,9 +489,9 @@ class Communication {
    * Ensure a url meets the requirements to be a profile uri.
    * @param {String} url
    * @param {Object} validationOptions
-   * @param {Boolean} validationOptions.allowLoopback
-   * @param {Boolean} validationOptions.resolveHostname
-   * @returns {Promise<void>}
+   * @param {Boolean=} validationOptions.allowLoopback default is false, following spec
+   * @param {Boolean=} validationOptions.resolveHostname default is false, following spec
+   * @returns {Promise<URL>}
    */
   async validateProfile(url, validationOptions) {
     const _scope = _fileScope('validateProfile');
@@ -526,11 +527,11 @@ class Communication {
 
   /**
    * Ensure a url meets the requirements to be a client identifier.
-   * Sets 'isLoopback' on returned URL object to true if hostname is or resolves to a loopback ip.
+   * Sets 'isLoopback' on returned URL object to true if hostname is - or resolves to - a loopback ip.
    * @param {String} url
    * @param {Object} validationOptions
-   * @param {Boolean} validationOptions.allowLoopback
-   * @param {Boolean} validationOptions.resolveHostname
+   * @param {Boolean=} validationOptions.allowLoopback default is true, following spec
+   * @param {Boolean=} validationOptions.resolveHostname default is true, following spec
    * @returns {Promise<URL>}
    */
   async validateClientIdentifier(url, validationOptions) {
@@ -574,7 +575,7 @@ class Communication {
    * Retrieve and parse client identifier endpoint data.
    * N.B. Assumes urlObj has passed validateClientIdentifier.
    * @param {URL} urlObj
-   * @returns {ClientIdentifierData|undefined} mf2 data filtered for h-app items, or undefined if url could not be fetched
+   * @returns {Promise<ClientIdentifierData|undefined>} mf2 data filtered for h-app items, or undefined if url could not be fetched
    */
   async fetchClientIdentifier(urlObj) {
     const _scope = _fileScope('fetchClientIdentifier');
@@ -647,8 +648,9 @@ class Communication {
   /**
    * Fetch the relevant microformat data from profile url h-card information,
    * and authorization server metadata.
+   * N.B. Assumes urlObj has passed validateProfile
    * @param {URL} urlObj
-   * @returns {ProfileData} mf2 data filtered for select fields from h-card
+   * @returns {Promise<ProfileData>} mf2 data filtered for select fields from h-card
    */
   async fetchProfile(urlObj) {
     const _scope = _fileScope('fetchProfile');
@@ -751,7 +753,7 @@ class Communication {
    * @param {String} codeVerifier
    * @param {String} clientId
    * @param {String} redirectURI
-   * @returns {Object}
+   * @returns {Promise<Object>}
    */
   async redeemCode(urlObj, code, codeVerifier, clientId, redirectURI) {
     const _scope = _fileScope('redeemCode');
@@ -790,7 +792,7 @@ class Communication {
    * @param {Strin} codeVerifier
    * @param {String} clientId
    * @param {String} redirectURI
-   * @returns {Object}
+   * @returns {Promise<Object>}
    */
   async redeemProfileCode(urlObj, code, codeVerifier, clientId, redirectURI) {
     return this.redeemCode(urlObj, code, codeVerifier, clientId, redirectURI);
@@ -802,6 +804,7 @@ class Communication {
    * @param {URL} introspectionUrlObj
    * @param {String} authorizationHeader
    * @param {String} token
+   * @returns {Promise<Object>}
    */
   async introspectToken(introspectionUrlObj, authorizationHeader, token) {
     const _scope = _fileScope('introspectToken');
@@ -863,7 +866,7 @@ class Communication {
    * @param {URL} resourceUrlObj
    * @param {URL} subjectUrlObj
    * @param {String} ticket
-   * @returns {Promise<AxiosResponse>}
+   * @returns {Promise<Response>}
    */
   async deliverTicket(ticketEndpointUrlObj, resourceUrlObj, subjectUrlObj, ticket) {
     const _scope = _fileScope('deliverTicket');