From: Justin Wind <justin.wind+git@gmail.com>
Date: Sat, 10 Jun 2023 18:55:01 +0000 (-0700)
Subject: minor doc fixes
X-Git-Tag: v1.3.0~2
X-Git-Url: https://git.squeep.com/?p=squeep-indieauth-helper;a=commitdiff_plain;h=6c3dbdc13dc125d4faa30d5138a8ada7d14e0ed1

minor doc fixes
---

diff --git a/README.md b/README.md
index 47c8cc6..b3f85bf 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # IndieAuth Helper
 
-Just some abstractions for interacting with IndieAuth sites, basically wrapping axios and mf2 parsing.
+Just some abstractions for interacting with IndieAuth sites, basically wrapping `got` and `microformats-parser` mf2 parsing and some other fiddly bits.
 
 This is currently quite opinionated, and likely is only really useful in the context of Squeep Framework Applications.
 
@@ -9,8 +9,8 @@ Notable methods on the Communication class:
 - `static async generatePKCE(length)`  
   Create a code and verifier for use in an IndieAuth transaction.
 
-- `validateProfile(url)`
-  Check that a urls meets specification requirements to be a profile.
+- `async validateProfile(url)`
+  Check that a url meets specification requirements to be a profile.
 
 - `async fetchProfile(urlObject)`  
   Retrieve profile information from an endpoint.
diff --git a/lib/common.js b/lib/common.js
index c1b8703..b52b819 100644
--- a/lib/common.js
+++ b/lib/common.js
@@ -27,6 +27,7 @@ const gotResponseLogData = (res) => {
     'statusMessage',
     'headers',
     'body',
+    'error',
   ]);
   if (typeof res.body === 'string') {
     data.body = logTruncate(data.body, 100);
diff --git a/lib/communication.js b/lib/communication.js
index 18a6e58..d160707 100644
--- 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');