Document class and module methods via JSDoc.

.eslintignore

@@ -1 +1,2 @@
 dist
+docs

.gitignore

@@ -86,3 +86,6 @@ typings/
 
 # DynamoDB Local files
 .dynamodb/
+
+# JSDoc output files
+docs

.jsdoc.json

@@ -0,0 +1,5 @@
+{
+  "opts": {
+    "template": "node_modules/minami"
+  }
+}

README.md

@@ -134,4 +134,5 @@ constructorio.recommendations.getUserFeaturedItems({ parameters }).then(function
 npm run lint          # run lint on source code and tests
 npm run test          # run tests
 npm run coverage      # run tests and serves coverage reports from localhost:8081
+npm run docs          # build and serve documentation from localhost:8082
 ```

package.json

@@ -8,7 +8,8 @@
     "test": "mocha ./spec/* --opts ./mocha.opts --recursive",
     "precoverage": "rm -rf ./coverage && rm -rf ./.nyc_output",
     "coverage": "nyc --all --reporter=html npm test",
-    "postcoverage": "http-server ./coverage -p 8081 -o -c-1"
+    "postcoverage": "http-server ./coverage -p 8081 -o -c-1",
+    "docs": "jsdoc --configure ./.jsdoc.json ./README.md --recurse ./src --destination ./docs && http-server ./docs -p 8082 -o -c-1"
   },
   "repository": {
     "type": "git",
@@ -36,6 +37,8 @@
     "eslint-config-airbnb-base": "^14.0.0",
     "eslint-plugin-import": "^2.18.2",
     "http-server": "^0.11.1",
+    "jsdoc": "^3.6.3",
+    "minami": "^1.2.3",
     "mocha": "^6.2.0",
     "mocha-jsdom": "^2.0.0",
     "nyc": "^14.1.1",

src/constructorio.js

@@ -8,7 +8,22 @@ const { recommendations } = require('./modules/recommendations');
 
 const { version } = require('../package.json');
 
+/**
+ * Class to instantiate the ConstructorIO client.
+ */
 class ConstructorIO {
+  /**
+   * @param {string} apiKey - Constructor.io API key
+   * @param {string} [serviceUrl='https://ac.cnstrc.com'] - API URL endpoint
+   * @param {string} [segments] - User segments
+   * @param {object} [testCells] - User test cells
+   * @param {string} [clientId] - Client ID, defaults to value supplied by 'constructorio-id'
+   * @param {string} [sessionId] - Session id, defaults to value supplied by 'constructorio-id'
+   * @property {object} [search] - Interface to {@link module:search}
+   * @property {object} [autocomplete] - Interface to {@link module:autocomplete}
+   * @property {object} [recommendations] - Interface to {@link module:recommendations}
+   * @returns {class}
+   */
   constructor(options = {}) {
     const {
       apiKey,

src/modules/autocomplete.js

@@ -5,9 +5,12 @@ import Promise from 'es6-promise';
 
 const { fetch } = fetchPonyfill({ Promise });
 
-/*
- * Autocomplete
- * - https://docs.constructor.io/rest-api.html#autocomplete
+/**
+ * Interface to autocomplete related API calls.
+ *
+ * @module autocomplete
+ * @inner
+ * @returns {object}
  */
 export function autocomplete(options) {
   // Create URL from supplied query (term) and parameters
@@ -63,7 +66,16 @@ export function autocomplete(options) {
   };
 
   return {
-    // Get autocomplete results for supplied query (term)
+    /**
+     * Retrieve autocomplete results from API
+     *
+     * @function getResults
+     * @param {object} [parameters] - Additional parameters to refine result set
+     * @param {number} [parameters.results] - The number of results to return
+     * @param {object} [parameters.filters] - Filters used to refine search
+     * @returns {Promise}
+     * @see https://docs.constructor.io/rest-api.html#autocomplete
+     */
     getResults: (query, parameters) => {
       const requestUrl = createAutocompleteUrl(query, parameters);
 

src/modules/recommendations.js

@@ -5,9 +5,12 @@ import Promise from 'es6-promise';
 
 const { fetch } = fetchPonyfill({ Promise });
 
-/*
- * Recommendations
- * - https://docs.constructor.io
+/**
+ * Interface to recommendations related API calls.
+ *
+ * @module recommendations
+ * @inner
+ * @returns {object}
  */
 export function recommendations(options) {
   // Create URL from supplied parameters
@@ -79,26 +82,60 @@ export function recommendations(options) {
     });
 
   return {
-    // Get alternative item recommendations for supplied query (term)
+    /**
+     * Get alternative item recommendations for supplied item id(s)
+     *
+     * @function getAlternativeItems
+     * @param {string|array} itemIds - Item ID(s) to retrieve recommendations for
+     * @param {object} [parameters] - Additional parameters to refine results
+     * @param {number} [parameters.results] - The number of results to return
+     * @returns {Promise}
+     * @see https://docs.constructor.io/rest-api.html
+     */
     getAlternativeItems: (itemIds, parameters) => {
       parameters = parameters || {};
       parameters.itemIds = itemIds;
 
       return requestAndProcessResponse(createRecommendationsUrl(parameters, 'alternative_items'), 'alternative_items');
     },
 
-    // Get complementary item recommendations for supplied query (term)
+    /**
+     * Get complementary item recommendations for supplied item id(s)
+     *
+     * @function getComplementaryItems
+     * @param {string|array} itemIds - Item ID(s) to retrieve recommendations for
+     * @param {object} [parameters] - Additional parameters to refine results
+     * @param {number} [parameters.results] - The number of results to return
+     * @returns {Promise}
+     * @see https://docs.constructor.io/rest-api.html
+     */
     getComplementaryItems: (itemIds, parameters) => {
       parameters = parameters || {};
       parameters.itemIds = itemIds;
 
       return requestAndProcessResponse(createRecommendationsUrl(parameters, 'complementary_items'), 'complementary_items');
     },
 
-    // Get recently viewed item recommendations for supplied query (term)
+    /**
+     * Get recently viewed item recommendations
+     *
+     * @function getRecentlyViewedItems
+     * @param {object} [parameters] - Additional parameters to refine results
+     * @param {number} [parameters.results] - The number of results to return
+     * @returns {Promise}
+     * @see https://docs.constructor.io/rest-api.html
+     */
     getRecentlyViewedItems: (parameters) => requestAndProcessResponse(createRecommendationsUrl(parameters, 'recently_viewed_items'), 'recently_viewed_items'),
 
-    // Get user featured item recommendations for supplied query (term)
+    /**
+     * Get user featured item recommendations
+     *
+     * @function getUserFeaturedItems
+     * @param {object} [parameters] - Additional parameters to refine results
+     * @param {number} [parameters.results] - The number of results to return
+     * @returns {Promise}
+     * @see https://docs.constructor.io/rest-api.html
+     */
     getUserFeaturedItems: (parameters) => requestAndProcessResponse(createRecommendationsUrl(parameters, 'user_featured_items'), 'user_featured_items'),
   };
 }

src/modules/search.js

@@ -5,9 +5,12 @@ import Promise from 'es6-promise';
 
 const { fetch } = fetchPonyfill({ Promise });
 
-/*
- * Search
- * - https://docs.constructor.io/rest-api.html#search
+/**
+ * Interface to search related API calls.
+ *
+ * @module search
+ * @inner
+ * @returns {object}
  */
 export function search(options) {
   // Create URL from supplied query (term) and parameters
@@ -135,7 +138,20 @@ export function search(options) {
   };
 
   return {
-    // Get search results for supplied query (term);
+    /**
+     * Retrieve search results from API
+     *
+     * @function getSearchResults
+     * @param {string} query - Term to use to perform a search
+     * @param {object} [parameters] - Additional parameters to refine result set
+     * @param {number} [parameters.page] - The page number of the results
+     * @param {number} [parameters.resultsPerPage] - The number of results per page to return
+     * @param {object} [parameters.filters] - Filters used to refine search
+     * @param {string} [parameters.sortBy='relevance'] - The sorting method
+     * @param {string} [parameters.sortOrder='descending'] - The sort order for search results
+     * @returns {Promise}
+     * @see https://docs.constructor.io/rest-api.html#search
+     */
     getSearchResults: (query, parameters) => {
       const requestUrl = createSearchUrl(query, parameters, options);
 
@@ -163,7 +179,19 @@ export function search(options) {
         });
     },
 
-    // Get browse results
+    /**
+     * Retrieve browse results from API
+     *
+     * @function getBrowseResults
+     * @param {object} [parameters] - Additional parameters to refine result set
+     * @param {number} [parameters.page] - The page number of the results
+     * @param {number} [parameters.resultsPerPage] - The number of results per page to return
+     * @param {object} [parameters.filters] - Filters used to refine search
+     * @param {string} [parameters.sortBy='relevance'] - The sorting method
+     * @param {string} [parameters.sortOrder='descending'] - The sort order for search results
+     * @returns {Promise}
+     * @see https://docs.constructor.io
+     */
     getBrowseResults(parameters) {
       const requestUrl = createBrowseUrl(parameters);