fix(docs): Change to jsdoc

contentful · Jun 2, 2017 · c024351 · c024351
1 parent 4191bd6
commit c024351
Show file tree

Hide file tree

Showing 5 changed files with 298 additions and 398 deletions.
diff --git a/jsdoc.json b/jsdoc.json
@@ -1,8 +1,30 @@
 {
-  "opts": {
-    "mainpagetitle": "contentful.js",
-    "template": "node_modules/contentful-sdk-jsdoc/jsdoc-template",
-    "readme": "README.md",
-    "package": "package.json"
-  }
+    "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
+    }
 }
diff --git a/lib/contentful.js b/lib/contentful.js
@@ -30,6 +30,7 @@ import version from '../version.js'
  * @prop {string=?} params.integration - Integration name and version e.g react/version
  * @returns {ContentfulClientAPI.ClientAPI}
  * @example
+ * const contentful = require('contentful')
  * const client = contentful.createClient({
  *  accessToken: 'myAccessToken',
  *  space: 'mySpaceId'

diff --git a/lib/create-contentful-api.js b/lib/create-contentful-api.js
@@ -77,8 +77,16 @@ export default function createContentfulApi ({http, shouldLinksResolve}) {
    * @memberof ContentfulClientAPI
    * @return {Promise<Entities.Space>} Promise for a Space
    * @example
+   * const contentful = require('contentful')
+   *
+   * const client = contentful.createClient({
+   *   space: '<space_id>',
+   *   accessToken: '<content_delivery_api_key>'
+   * })
+   * // returns the space object with the above <space-id>
    * client.getSpace()
-   * .then(space => console.log(space))
+   * .then((space) => console.log(space))
+   * .catch(console.error)
    */
   function getSpace () {
     return http.get('')
@@ -91,8 +99,16 @@ export default function createContentfulApi ({http, shouldLinksResolve}) {
    * @param  {string} id
    * @return {Promise<Entities.ContentType>} Promise for a Content Type
    * @example
-   * client.getContentType('contentTypeId')
-   * .then(contentType => console.log(contentType))
+   * const contentful = require('contentful')
+   *
+   * const client = contentful.createClient({
+   *   space: '<space_id>',
+   *   accessToken: '<content_delivery_api_key>'
+   * })
+   *
+   * client.getContentType('<content_type_id>')
+   * .then((contentType) => console.log(contentType))
+   * .catch(console.error)
    */
   function getContentType (id) {
     return http.get('content_types/' + id)
@@ -105,8 +121,16 @@ export default function createContentfulApi ({http, shouldLinksResolve}) {
    * @param  {Object=} query - Object with search parameters. Check the <a href="https://www.contentful.com/developers/docs/javascript/tutorials/using-js-cda-sdk/#retrieving-entries-with-search-parameters">JS SDK tutorial</a> and the <a href="https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters">REST API reference</a> for more details.
    * @return {Promise<Entities.ContentTypeCollection>} Promise for a collection of Content Types
    * @example
+   * const contentful = require('contentful')
+   *
+   * const client = contentful.createClient({
+   *   space: '<space_id>',
+   *   accessToken: '<content_delivery_api_key>'
+   * })
+   *
    * client.getContentTypes()
-   * .then(contentTypes => console.log(contentTypes.items))
+   * .then((response) => console.log(response.items))
+   * .catch(console.error)
    */
   function getContentTypes (query = {}) {
     return http.get('content_types', createRequestConfig({query: query}))
@@ -120,8 +144,16 @@ export default function createContentfulApi ({http, shouldLinksResolve}) {
    * @param  {Object=} query - Object with search parameters. In this method it's only useful for `locale`.
    * @return {Promise<Entities.Entry>} Promise for an Entry
    * @example
-   * client.getEntry('entryId')
-   * .then(entry => console.log(entry))
+   * const contentful = require('contentful')
+   *
+   * const client = contentful.createClient({
+   *   space: '<space_id>',
+   *   accessToken: '<content_delivery_api_key>'
+   * })
+   *
+   * client.getEntry('<entry_id>')
+   * .then((entry) => console.log(entry))
+   * .catch(console.error)
    */
   function getEntry (id, query = {}) {
     normalizeSelect(query)
@@ -133,11 +165,18 @@ export default function createContentfulApi ({http, shouldLinksResolve}) {
    * Gets a collection of Entries
    * @memberof ContentfulClientAPI
    * @param  {Object=} query - Object with search parameters. Check the <a href="https://www.contentful.com/developers/docs/javascript/tutorials/using-js-cda-sdk/#retrieving-entries-with-search-parameters">JS SDK tutorial</a> and the <a href="https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters">REST API reference</a> for more details.
-   * @param  {boolean=} query.resolveLinks - When true, links to other Entries or Assets are resolved. Default: true.
    * @return {Promise<Entities.EntryCollection>} Promise for a collection of Entries
    * @example
-   * client.getEntries({content_type: 'contentTypeId'})
-   * .then(entries => console.log(entries.items))
+   * const contentful = require('contentful')
+   *
+   * const client = contentful.createClient({
+   *   space: '<space_id>',
+   *   accessToken: '<content_delivery_api_key>'
+   * })
+   *
+   * client.getEntries()
+   * .then((response) => console.log(response.items))
+   * .catch(console.error)
    */
   function getEntries (query = {}) {
     const resolveLinks = shouldLinksResolve(query)
@@ -153,8 +192,16 @@ export default function createContentfulApi ({http, shouldLinksResolve}) {
    * @param  {Object=} query - Object with search parameters. In this method it's only useful for `locale`.
    * @return {Promise<Entities.Asset>} Promise for an Asset
    * @example
-   * client.getAsset('assetId')
-   * .then(asset => console.log(asset))
+   * const contentful = require('contentful')
+   *
+   * const client = contentful.createClient({
+   *   space: '<space_id>',
+   *   accessToken: '<content_delivery_api_key>'
+   * })
+   *
+   * client.getAsset('<asset_id>')
+   * .then((asset) => console.log(asset))
+   * .catch(console.error)
    */
   function getAsset (id, query = {}) {
     normalizeSelect(query)
@@ -168,8 +215,16 @@ export default function createContentfulApi ({http, shouldLinksResolve}) {
    * @param  {Object=} query - Object with search parameters. Check the <a href="https://www.contentful.com/developers/docs/javascript/tutorials/using-js-cda-sdk/#retrieving-entries-with-search-parameters">JS SDK tutorial</a> and the <a href="https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters">REST API reference</a> for more details.
    * @return {Promise<Entities.AssetCollection>} Promise for a collection of Assets
    * @example
+   * const contentful = require('contentful')
+   *
+   * const client = contentful.createClient({
+   *   space: '<space_id>',
+   *   accessToken: '<content_delivery_api_key>'
+   * })
+   *
    * client.getAssets()
-   * .then(assets => console.log(assets.items))
+   * .then((response) => console.log(response.items))
+   * .catch(console.error)
    */
   function getAssets (query = {}) {
     normalizeSelect(query)
@@ -192,8 +247,22 @@ export default function createContentfulApi ({http, shouldLinksResolve}) {
    * @param  {boolean=} query.resolveLinks - When true, links to other Entries or Assets are resolved. Default: true.
    * @return {Promise<Sync.SyncCollection>} Promise for the collection resulting of a sync operation
    * @example
-   * client.sync()
-   * .then((response) => console.log(response.entries, response.assets, response.nextSyncToken))
+   * const contentful = require('contentful')
+   *
+   * const client = contentful.createClient({
+   *   space: '<space_id>',
+   *   accessToken: '<content_delivery_api_key>'
+   * })
+   *
+   * client.sync({
+   *   initial: true
+   * })
+   * .then((response) => console.log({
+   *   entries: response.entries,
+   *   assets: response.assets,
+   *   nextSyncToken: response.nextSyncToken
+   * }))
+   * .catch(console.error)
    */
   function sync (query = {}) {
     const resolveLinks = shouldLinksResolve(query)

diff --git a/package.json b/package.json
@@ -21,9 +21,12 @@
     "build:standalone": "BABEL_ENV=webpack webpack && BABEL_ENV=webpack NODE_ENV=production webpack ",
     "build:standalone:log": "BABEL_ENV=webpack npm run build && BABEL_ENV=webpack NODE_ENV=production webpack --json --profile > webpack-build-log.json",
     "build:modules": "BABEL_ENV=webpack babel lib -d dist/es6-modules",
-    "docs:build": "esdoc -c esdoc.json",
+    "build:ci": "npm run vendor:version && npm run build:standalone",
+    "build:standalone": "BABEL_ENV=webpack webpack && BABEL_ENV=webpack webpack -p --output-filename contentful.min.js",
+    "build:standalone:log": "BABEL_ENV=webpack npm run build && webpack -p --json --profile --output-filename contentful.min.js > webpack-build-log.json",
+    "docs:build": "jsdoc -c jsdoc.json",
     "docs:dev": "npm run build && npm run docs:build",
-    "docs:watch": "watchy -w lib npm run docs:dev",
+    "docs:watch": "nodemon --exec npm run docs:dev -w lib",
     "docs:publish": "npm run docs:build && ./node_modules/contentful-sdk-jsdoc/bin/publish-docs.sh contentful.js contentful",
     "lint": "eslint lib test",
     "pretest": "npm run lint",
@@ -51,6 +54,7 @@
   },
   "types": "./index.d.ts",
   "files": [
+    "index.js",
     "version.js",
     "index.d.ts",
     "dist",
@@ -78,10 +82,9 @@
     "babel-template": "^6.22.0",
     "babel-types": "^6.22.0",
     "blue-tape": "^1.0.0",
-    "contentful-sdk-jsdoc": "^1.2.2",
+    "contentful-sdk-jsdoc": "^2.2.0",
     "coveralls": "^2.11.9",
     "cz-conventional-changelog": "^1.1.6",
-    "esdoc": "^0.5.2",
     "eslint": "^3.16.0",
     "eslint-config-standard": "^6.2.1",
     "eslint-plugin-promise": "^3.4.2",
@@ -99,6 +102,7 @@
     "karma-webpack": "^2.0.2",
     "lodash-webpack-plugin": "^0.11.2",
     "mkdirp": "^0.5.1",
+    "nodemon": "^1.11.0",
     "require-all": "^2.2.0",
     "rimraf": "^2.6.0",
     "semantic-release": "^6.3.2",