fix(docs): Change to jsdoc

Author: Khaledgarbaya

jsdoc.json

@@ -0,0 +1,30 @@
+{
+    "tags": {
+        "allowUnknownTags": true
+    },
+    "source": {
+        "include": [
+            "lib/",
+            "./README.md"
+        ]
+    },
+    "opts": {
+        "encoding": "utf8",
+        "template": "node_modules/contentful-sdk-jsdoc/jsdoc-template",
+        "destination": "out/",
+        "recurse": true,
+        "verbose": true
+    },
+    "templates": {
+        "cleverLinks": false,
+        "monospaceLinks": false,
+        "default": {
+            "outputSourceFiles": true,
+            "includeDate": false
+        }
+    },
+    "docdash": {
+        "static": false,
+        "sort": true
+    }
+}

lib/contentful-management.js

@@ -11,17 +11,28 @@ import {createHttpClient, getUserAgentHeader} from 'contentful-sdk-core'
 import createContentfulApi from './create-contentful-api'
 import version from '../version'
 /**
- * @typedef {ContentfulManagement} ContentfulManagement
- * @property {function(params: {accessToken: string, insecure?: boolean, host?: string, hostUpload?: string, httpAgent?: Object, httpsAgent?: Object, headers?: Object, proxy?:Object, application?: string, integration?: string}, retryOnError?: boolean): ClientAPI} createClient - Create a client instance, this is the entry point to the library
- *
+ * Create a client instance
+ * @func
+ * @name createClient
+ * @memberof contentfulManagement
+ * @param {object} params - Client initialization parameters
+ * @prop {string=} params.accessToken - Contentful CDA Access Token
+ * @prop {boolean=?} params.insecure - Requests will be made over http instead of the default https (default: false)
+ * @prop {boolean=?} params.retryOnError - If we should retry on errors and 429 rate limit exceptions (default: true)
+ * @prop {string=?} params.host - API host (default: cda.contentful.com)
+ * @prop {string=?} params.hostUpload - direct file upload host (default : upload.contentful.com)
+ * @prop {Object=?} params.httpAgent - Optional Node.js HTTP agent for proxying (see <a href="https://nodejs.org/api/http.html#http_class_http_agent">Node.js docs</a> and <a href="https://www.npmjs.com/package/https-proxy-agent">https-proxy-agent</a>)
+ * @prop {Object=?} params.httpsAgent - Optional Node.js HTTP agent for proxying (see <a href="https://nodejs.org/api/http.html#http_class_http_agent">Node.js docs</a> and <a href="https://www.npmjs.com/package/https-proxy-agent">https-proxy-agent</a>)
+ * @prop {Object=?} params.proxy - Optional Axios proxy (see <a href="https://github.com/mzabriskie/axios#request-config"> axios docs </a>)
+ * @prop {object=?} params.headers - Optional additional headers
+ * @prop {string=?} params.application - Application name and version e.g myApp/version
+ * @prop {string=?} params.integration - Integration name and version e.g react/version
+ * @returns {ContentfulClientAPI.ClientAPI}
  * @example
- * // require contentful-management
- * var contentfulManagement = require('contentful-management')
- * var client = contentfulManagement.createClient({
- * // This is the access token for this space. Normally you get both ID and the token in the Contentful web app
- * accessToken: 'YOUR_ACCESS_TOKEN'
+ * const client = contentfulManagement.createClient({
+ *  accessToken: 'myAccessToken'
  * })
-*/
+ */
 export function createClient (params) {
   const defaultParameters = {
     defaultHostname: 'api.contentful.com',

lib/create-contentful-api.js

@@ -1,14 +1,46 @@
-import errorHandler from './error-handler'
-import entities from './entities'
+/**
+ * Contentful Management API Client. Contains methods which allow access to
+ * any operations that can be performed with a management token.
+ * @namespace ContentfulClientAPI
+ */
+
+/**
+ * Types for meta information found across the different entities in Contentful
+ * @namespace Meta
+ */
+
+/**
+ * System metadata. See <a href="https://www.contentful.com/developers/docs/references/content-delivery-api/#/introduction/common-resource-attributes">Common Resource Attributes</a> for more details.
+ * @memberof Meta
+ * @typedef Sys
+ * @prop {string} type
+ * @prop {string} id
+ * @prop {Meta.Link} space
+ * @prop {string} createdAt
+ * @prop {string} updatedAt
+ * @prop {number} revision
+ */
 
 /**
- * @typedef {ClientAPI} ClientAPI
- * @property {function(id: string): Promise<Space>} getSpace - Gets a space with the spcified id
- * @property {function(): Promise<SpaceCollection>} getSpaces - Gets a collection of spaces
- * @property {function(data: {name: string}): Promise<Space>} createSpace - Creates a space
- * @property {function(): Promise<OrganizationCollection>} getOrganizations - Gets a collection of Organizations
+ * Link to another entity. See <a href="https://www.contentful.com/developers/docs/concepts/links/">Links</a> for more details.
+ * @memberof Meta
+ * @typedef Link
+ * @prop {string} type - type of this entity. Always link.
+ * @prop {string} id
+ * @prop {string} linkType - type of this link. If defined, either Entry or Asset
  */
 
+/**
+ * @memberof ContentfulClientAPI
+ * @typedef {Object} ClientAPI
+ * @prop {function} getSpace
+ * @prop {function} getSpaces
+ * @prop {function} createSpace
+ */
+
+import errorHandler from './error-handler'
+import entities from './entities'
+
 /**
  * Creates API object with methods to access functionality from Contentful's
  * Management API
@@ -24,10 +56,18 @@ export default function createClientApi ({ http }) {
 
   /**
    * Gets all spaces
-   * @memberof ClientAPI   * @return {Promise<Space.SpaceCollection>} Promise for a collection of Spaces
+   * @memberof ContentfulClientAPI
+   * @return {Promise<Space.SpaceCollection>} Promise for a collection of Spaces
    * @example
+   * const contentful = require('contentful-management')
+   *
+   * const client = contentful.createClient({
+   *   accessToken: '<content_management_api_key>'
+   * })
+   *
    * client.getSpaces()
-   * .then(spaces => console.log(spaces.items))
+   * .then((response) => console.log(response.items))
+   * .catch(console.error)
    */
   function getSpaces () {
     return http.get('')
@@ -36,12 +76,19 @@ export default function createClientApi ({ http }) {
 
   /**
    * Gets a space
-   * @memberof ClientAPI
+   * @memberof ContentfulClientAPI
    * @param {string} id - Space ID
    * @return {Promise<Space.Space>} Promise for a Space
    * @example
-   * client.getSpace('spaceid')
-   * .then(space => console.log(space))
+   * const contentful = require('contentful-management')
+   *
+   * const client = contentful.createClient({
+   *   accessToken: '<content_management_api_key>'
+   * })
+   *
+   * client.getSpace('<space_id>')
+   * .then((space) => console.log(space))
+   * .catch(console.error)
    */
   function getSpace (id) {
     return http.get(id)
@@ -50,14 +97,23 @@ export default function createClientApi ({ http }) {
 
   /**
    * Creates a space
-   * @memberof ClientAPI
+   * @memberof ContentfulClientAPI
    * @see {Space.Space}
    * @param {object} data - Object representation of the Space to be created
    * @param {string=} organizationId - Organization ID, if the associated token can manage more than one organization.
    * @return {Promise<Space.Space>} Promise for the newly created Space
    * @example
-   * client.createSpace({name: 'Space Name'})
-   * .then(space => console.log(space))
+   * const contentful = require('contentful-management')
+   *
+   * const client = contentful.createClient({
+   *   accessToken: '<content_management_api_key>'
+   * })
+   *
+   * client.createSpace({
+   *   name: 'Name of new space'
+   * })
+   * .then((space) => console.log(space))
+   * .catch(console.error)
    */
   function createSpace (data, organizationId) {
     return http.post('', data, {
@@ -71,8 +127,11 @@ export default function createClientApi ({ http }) {
    * @memberof ClientAPI
    * @return {Promise<OrganizationCollection>} Promise for a collection of Organizations
    * @example
+   * const contentful = require('contentful-management')
+   *
    * space.getOrganizations()
    * .then(result => console.log(result.items))
+   * .catch(console.error)
    */
   function getOrganizations () {
     const baseURL = http.defaults.baseURL.replace('/spaces/', '/organizations/')