feat: add missing documentation for types (#1853)

DOCS.md

@@ -29,7 +29,12 @@
   <img src="https://img.badgesize.io/https://unpkg.com/contentful/dist/contentful.browser.min.js?compression=gzip" alt="GZIP bundle size">
 </a>
 
-[TODO: write few sentences]
+Contentful.js is a JavaScript library for the Contentful [Content Delivery API](https://www.contentful.com/developers/docs/references/content-delivery-api/) and [Content Preview API](https://www.contentful.com/developers/docs/references/content-preview-api/).
+
+Code is documented using TypeDoc and these pages are auto-generated and published with each new version.
+
+- For API and client documentation, please refer to the list below.
+- For type definitions and descriptions, please refer to the list in the sidebar.
 
 ## Namespaces
 

lib/contentful.ts

@@ -5,7 +5,7 @@
 
 import axios from 'axios'
 import { createHttpClient, getUserAgentHeader } from 'contentful-sdk-core'
-import createGlobalOptions from './create-global-options'
+import { createGlobalOptions } from './create-global-options'
 import { makeClient } from './make-client'
 import type { AxiosAdapter, AxiosRequestConfig } from 'axios'
 import { validateRemoveUnresolvedParam, validateResolveLinksParam } from './utils/validate-params'
@@ -17,8 +17,8 @@ import { ContentfulClientApi } from './types'
 export type ClientLogLevel = 'error' | 'warning' | 'info' | string
 
 /**
- * @category Client
  * Client initialization parameters
+ * @category Client
  */
 export interface CreateClientParams {
   /**
@@ -88,8 +88,8 @@ export interface CreateClientParams {
   /**
    * A log handler function to process given log messages and errors.
    * (The default can be found at: https://github.com/contentful/contentful-sdk-core/blob/master/src/create-http-client.ts)
-   * @param level Log level, e.g. error, warning, or info
-   * @param data Log data
+   * @param level - Log level, e.g. error, warning, or info
+   * @param data - Log data
    */
   logHandler?: (level: ClientLogLevel, data?: Record<string, any> | string) => void
   /**
@@ -104,15 +104,17 @@ export interface CreateClientParams {
 }
 
 /**
- * @category Client
  * Create a client instance
- * @param params Client initialization parameters
+ * @param params - Client initialization parameters
+ * @category Client
  * @example
+ * ```typescript
  * const contentful = require('contentful')
  * const client = contentful.createClient({
  *   accessToken: 'myAccessToken',
  *   space: 'mySpaceId'
  * })
+ * ```
  */
 export function createClient(params: CreateClientParams): ContentfulClientApi<undefined> {
   if (!params.accessToken) {

lib/create-global-options.ts

@@ -1,11 +1,6 @@
 /**
- * Link resolution can be set globally, or it can be turned off for the methods
- * which make use of it. The local setting always overrides the global setting.
- * @private
- * @param {boolean} globalSetting - Global library setting for link resolution
- * @returns {function} Link resolver method preconfigured with global setting
+ * @category Client
  */
-
 export interface GlobalOptionsParams {
   environment?: string
   space?: string
@@ -20,12 +15,22 @@ export type GetGlobalOptions = (
   globalOptions?: GlobalOptionsParams
 ) => Required<GlobalOptionsParams>
 
-export default function createGlobalOptions(
+/**
+ * @param globalSettings - Global library settings
+ * @returns getGlobalSettings - Method returning client settings
+ * @category Client
+ */
+export function createGlobalOptions(
   globalSettings: Required<GlobalOptionsParams>
 ): GetGlobalOptions {
   /**
-   * Link resolver method
-   * @param {Object} query - regular query object used for collection endpoints
+   * Method merging pre-configured global options and provided local parameters
+   * @param query - regular query object used for collection endpoints
+   * @param query.environment - optional name of the environment
+   * @param query.space - optional space ID
+   * @param query.spaceBaseUrl - optional base URL for the space
+   * @param query.environmentBaseUrl - optional base URL for the environment
+   * @returns global options
    */
   return function getGlobalOptions(query?: GlobalOptionsParams) {
     return Object.assign({}, globalSettings, query)

lib/paged-sync.ts

@@ -1,7 +1,3 @@
-/**
- * See <a href="https://www.contentful.com/developers/docs/concepts/sync/">Synchronization</a> for more information.
- * @namespace Sync
- */
 import resolveResponse from 'contentful-resolve-response'
 import { AxiosInstance, createRequestConfig, freezeSys, toPlainObject } from 'contentful-sdk-core'
 import mixinStringifySafe from './mixins/stringify-safe'
@@ -19,13 +15,7 @@ import {
 import { ChainOptions, ModifiersFromOptions } from './utils/client-helpers'
 
 /**
- * This module retrieves all the available pages for a sync operation
- * @private
- * @param {AxiosInstance} http - HTTP client
- * @param {SyncQuery} query - Query object
- * @param {SyncOptions} options - Sync options object
- * @param {boolean} [options.paginate = true] - If further sync pages should automatically be crawled
- * @return {Promise<SyncCollection>}
+ * Retrieves all the available pages for a sync operation
  */
 export default async function pagedSync<
   EntrySkeleton extends EntrySkeletonType,
@@ -85,8 +75,8 @@ export default async function pagedSync<
 
 /**
  * @private
- * @param {Array<Entry|Array|DeletedEntry|DeletedAsset>} items
- * @return {Object} Entities mapped to an object for each entity type
+ * @param items
+ * @returns Entities mapped to an object for each entity type
  */
 function mapResponseItems(items): any {
   const reducer = (type) => {
@@ -128,14 +118,7 @@ function createRequestQuery(originalQuery: SyncPageQuery): SyncPageQuery {
  * Otherwise, if the response contains a nextSyncUrl, extracts the sync token
  * and returns it.
  * On each call of this function, any retrieved items are collected in the
- * supplied items array, which gets returned in the end
- * @private
- * @param {AxiosInstance} http
- * @param {Array<Entry|Asset|DeletedEntry|DeletedAsset>} items
- * @param {SyncPageQuery} query
- * @param {SyncOptions} options - Sync page options object
- * @param {boolean} [options.paginate = true] - If further sync pages should automatically be crawled
- * @return {Promise<SyncPageResponse>}
+ * supplied items array, which gets returned in the end.
  */
 async function getSyncPage(
   http: AxiosInstance,

lib/types/asset.ts

@@ -5,7 +5,7 @@ import { EntitySys } from './sys'
 import { ChainModifiers } from './client'
 
 /**
- * @module Asset
+ * @category Asset
  */
 export interface AssetDetails {
   size: number
@@ -35,7 +35,11 @@ export interface AssetFields {
 }
 
 /**
+ * Assets are binary files in a Contentful space
  * @category Asset
+ * @typeParam Modifiers - The chain modifiers used to configure the client. They’re set automatically when using the client chain modifiers.
+ * @typeParam Locales - If provided for a client using `allLocales` modifier, response type defines locale keys for asset field values.
+ * @see {@link https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/assets | Documentation}
  */
 export interface Asset<
   Modifiers extends ChainModifiers = ChainModifiers,
@@ -74,14 +78,19 @@ export type AssetMimeType =
   | 'markup'
 
 /**
+ * A collection of assets
  * @category Asset
+ * @typeParam Modifiers - The chain modifiers used to configure the client. They’re set automatically when using the client chain modifiers.
+ * @typeParam Locales - If provided for a client using `allLocales` modifier, response type defines locale keys for asset field values.
+ * @see {@link https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/assets | Documentation}
  */
 export type AssetCollection<
   Modifiers extends ChainModifiers = ChainModifiers,
   Locales extends LocaleCode = LocaleCode
 > = ContentfulCollection<Asset<Modifiers, Locales>>
 
 /**
+ * System managed metadata for assets
  * @category Asset
  */
 export type AssetSys = EntitySys & {

lib/types/client.ts

@@ -9,7 +9,7 @@ import {
   EntrySkeletonType,
   TagQueries,
 } from './query'
-import { SyncCollection, SyncQuery } from './sync'
+import { SyncCollection, SyncOptions, SyncQuery } from './sync'
 import { Tag, TagCollection } from './tag'
 import { AssetKey } from './asset-key'
 import { Entry, EntryCollection } from './entry'
@@ -39,13 +39,13 @@ export type AddChainModifier<
 /**
  * Contentful Delivery API Client. Contains methods which allow access to the different kinds of entities present in Contentful (Entries, Assets, etc).
  * @category Client
- * @typeParam Modifiers The chain modifiers used to configure the client. They’re set automatically when using the client chain modifiers.
+ * @typeParam Modifiers - The chain modifiers used to configure the client. They’re set automatically when using the client chain modifiers.
  */
 export interface ContentfulClientApi<Modifiers extends ChainModifiers> {
   /**
    * Fetches a content type
-   * @param id The content type’s ID
-   * @return Promise for a content type
+   * @param id - The content type’s ID
+   * @returns Promise for a content type
    * @example
    * ```typescript
    * import * as contentful from 'contentful'
@@ -63,7 +63,7 @@ export interface ContentfulClientApi<Modifiers extends ChainModifiers> {
 
   /**
    * Fetches a collection of content types
-   * @return Promise for a collection of content types
+   * @returns Promise for a collection of content types
    * @example
    * ```typescript
    * import * as contentful from 'contentful'
@@ -81,7 +81,7 @@ export interface ContentfulClientApi<Modifiers extends ChainModifiers> {
 
   /**
    * Fetches the space which the client is currently configured to use
-   * @return Promise for the space
+   * @returns Promise for the space
    * @example
    * ```typescript
    * import * as contentful from 'contentful'
@@ -99,7 +99,7 @@ export interface ContentfulClientApi<Modifiers extends ChainModifiers> {
 
   /**
    * Fetches a collection of locales
-   * @return Promise for a collection of locales
+   * @returns Promise for a collection of locales
    * @example
    * ```typescript
    * import * as contentful from 'contentful'
@@ -118,10 +118,25 @@ export interface ContentfulClientApi<Modifiers extends ChainModifiers> {
 
   /**
    * Synchronizes either all the content or only new content since last sync.
-   * See <a href="https://www.contentful.com/developers/docs/concepts/sync/">Sync API</a> for more information.
    * <strong> Important note: </strong> The Sync API endpoint does not support include or link resolution.
-   * However, contentful.js is can do link resolution on the client side for the initial sync.
+   * However, contentful.js can do link resolution on the client side for the initial sync.
    * For the delta sync (using nextSyncToken) link resolution is not possible since the sdk won’t have access to all linked entities.
+   * @param query - Query object
+   * @param query.initial - Optional, unless first sync call
+   * @param query.limit - Optional, sets the page size for the number of retrieved entries
+   * @param query.nextSyncToken - Optional, used in subsequent sync calls
+   * @param query.nextPageToken - Optional, used in subsequent sync calls
+   * @param query.type - Optional, query for specific entities
+   * @param query.content_type - Query for specific content types; optional,
+   * unless `query.type` is defined as `Entry`
+   * @param syncOptions
+   * @param syncOptions.paginate - Configures the client to call the sync API recursively,
+   * collecting all items from responses into one collection
+   * @typeParam EntrySkeleton - Shape of entity fields used to calculate dynamic keys
+   * @typeParam Modifiers - The chain modifiers used to configure the client. They’re set automatically when using the client chain modifiers.
+   * @typeParam Locales - If provided for a client using `allLocales` modifier, response type defines locale keys for entity field values.
+   * @see {@link https://www.contentful.com/developers/docs/concepts/sync/ | Documentation}
+   * @see {@link https://www.contentful.com/developers/docs/javascript/tutorials/using-the-sync-api-with-js/ | Tutorial for using sync API}
    * @example
    * ```typescript
    * import * as contentful from 'contentful'
@@ -146,13 +161,14 @@ export interface ContentfulClientApi<Modifiers extends ChainModifiers> {
     Modifiers extends ChainModifiers = ChainModifiers,
     Locales extends LocaleCode = LocaleCode
   >(
-    query: SyncQuery
+    query: SyncQuery,
+    syncOptions?: SyncOptions
   ): Promise<SyncCollection<EntrySkeleton, Modifiers, Locales>>
 
   /**
    * Fetches a tag
-   * @param id The tag’s ID
-   * @return Promise for a tag
+   * @param id - The tag’s ID
+   * @returns Promise for a tag
    * @example
    * ```typescript
    * import * as contentful from 'contentful'
@@ -170,7 +186,7 @@ export interface ContentfulClientApi<Modifiers extends ChainModifiers> {
 
   /**
    * Gets a collection of Tags
-   * @return Promise for a collection of tags
+   * @returns Promise for a collection of tags
    * @example
    * ```typescript
    * import * as contentful from 'contentful'
@@ -188,7 +204,7 @@ export interface ContentfulClientApi<Modifiers extends ChainModifiers> {
 
   /**
    * Creates an asset key for signing asset URLs (Embargoed Assets)
-   * @return Promise for an asset key
+   * @returns Promise for an asset key
    * @example
    * ```typescript
    * import * as contentful from 'contentful'
@@ -208,7 +224,9 @@ export interface ContentfulClientApi<Modifiers extends ChainModifiers> {
    * Fetches an entry
    * @param id - The entry’s ID
    * @param query - Object with search parameters. In this method it's only used for `locale` when querying.
-   * @return Promise for an entry
+   * @returns Promise for an entry
+   * @typeParam EntrySkeleton - Shape of entry fields used to calculate dynamic keys
+   * @typeParam Locales - If provided for a client using `allLocales` modifier, response type defines locale keys for entry field values.
    * @example
    * ```typescript
    * const contentful = require('contentful')
@@ -232,8 +250,12 @@ export interface ContentfulClientApi<Modifiers extends ChainModifiers> {
 
   /**
    * Fetches a collection of Entries
-   * @param 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 for a collection of Entries
+   * @param query - Object with search parameters
+   * @returns Promise for a collection of Entries
+   * @typeParam EntrySkeleton - Shape of entry fields used to calculate dynamic keys
+   * @typeParam Locales - If provided for a client using `allLocales` modifier, response type defines locale keys for entry field values.
+   * @see {@link https://www.contentful.com/developers/docs/javascript/tutorials/using-js-cda-sdk/#retrieving-entries-with-search-parameters | JS SDK tutorial}
+   * @see {@link https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters | REST API reference}
    * @example
    * ```typescript
    * const contentful = require('contentful')
@@ -256,7 +278,9 @@ export interface ContentfulClientApi<Modifiers extends ChainModifiers> {
 
   /**
    * Parse raw json data into a collection of entries. objects.Links will be resolved also
-   * @param data json data
+   * @param data - json data
+   * @typeParam EntrySkeleton - Shape of entry fields used to calculate dynamic keys
+   * @typeParam Locales - If provided for a client using `allLocales` modifier, response type defines locale keys for entry field values.
    * @example
    * ```typescript
    * const data = {items: [
@@ -300,7 +324,8 @@ export interface ContentfulClientApi<Modifiers extends ChainModifiers> {
    * Fetches an asset
    * @param id
    * @param query - Object with search parameters. In this method it's only useful for `locale`.
-   * @return Promise for an asset
+   * @returns Promise for an asset
+   * @typeParam Locales - If provided for a client using `allLocales` modifier, response type defines locale keys for asset field values.
    * @example
    * const contentful = require('contentful')
    *
@@ -319,8 +344,11 @@ export interface ContentfulClientApi<Modifiers extends ChainModifiers> {
 
   /**
    * Fetches a collection of assets
-   * @param 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 for a collection of Assets
+   * @param query - Object with search parameters
+   * @see {@link https://www.contentful.com/developers/docs/javascript/tutorials/using-js-cda-sdk/#retrieving-entries-with-search-parameters | JS SDK tutorial}
+   * @see {@link https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters | REST API reference}
+   * @returns Promise for a collection of Assets
+   * @typeParam Locales - If provided for a client using `allLocales` modifier, response type defines locale keys for asset field values.
    * @example
    * const contentful = require('contentful')
    *

lib/types/collection.ts

@@ -2,7 +2,7 @@
  * A wrapper object containing additional information for
  * a collection of Contentful resources
  * @category Entity
- * @see {@link https://www.contentful.com/developers/docs/references/content-delivery-api/#/introduction/collection-resources-and-pagination | CDA documentation on Collections}
+ * @see {@link https://www.contentful.com/developers/docs/references/content-delivery-api/#/introduction/collection-resources-and-pagination | Documentation}
  */
 export interface ContentfulCollection<T> {
   total: number