Add examples to IURlConfig interfaces and hide private interfaces (#346)

- Hide private interfaces that aren't needed yet (they'll be needed for node)
- Add examples to existing members

Author: patrick-tolosa

src/config/interfaces/Config/IAccountConfig.ts

@@ -1,3 +1,6 @@
+/**
+ * @private
+ */
 interface IAccountConfig {
   provisioningApiKey?: string;
   provisioningApiSecret?: string;

src/config/interfaces/Config/IApiConfig.ts

@@ -1,3 +1,6 @@
+/**
+ * @private
+ */
 interface IApiConfig {
   apiProxy?: string;
   connectionTimeout?: number;

src/config/interfaces/Config/IAuthTokenConfig.ts

@@ -5,6 +5,8 @@
  * Defines the configuration for delivering token-based authenticated media assets.</br>
  * <b>Learn more:</b> {@link https://cloudinary.com/documentation/control_access_to_media#delivering_token_based_authenticated_media_assets|Delivering token based authenticated media assets}
  *
+ * @private
+ *
  * @prop {string} token_name
  * @prop {string} duration
  * @prop {string} start_time

src/config/interfaces/Config/ICloudConfig.ts

@@ -8,6 +8,19 @@ import IAuthTokenConfig from "./IAuthTokenConfig";
  * @prop {string} [apiKey]
  * @prop {string} [apiSecret]
  * @prop {IAuthTokenConfig} [authToken]
+ * @example
+ *  * import Cloudinary from '@cloudinary/base';
+ * // The Cloudinary Instance accepts a CloudConfig under the `cloud` key
+ * const cld = new Cloudinary({
+ *  // the cloudConfig
+ *  cloud: {
+ *       cloudName: 'demo'
+ *   },
+ *   // the urlConfig
+ *   url: {
+ *         // ... urlConfig is optional.
+ *   }
+ * });
  */
 interface ICloudConfig {
   cloudName?: string;

src/config/interfaces/Config/ICloudinaryAssetConfigurations.ts

@@ -4,11 +4,25 @@ import ICloudConfig from "./ICloudConfig";
 /**
  * @name ICloudinaryAssetConfigurations
  * @summary config
- * @description
- * Defines the configuration needed to create URLs for cloudinary assets
+ * @description Defines the configuration needed to create URLs for cloudinary assets
  *
  * @prop {ICloudConfig} cloud
  * @prop {IURLConfig} url
+ * @example
+ *  * import Cloudinary from '@cloudinary/base';
+ * // The Cloudinary Instance accepts an ICloudinaryAssetConfigurations as an argument
+ * // ICloudinaryAssetConfigurations is built from two parts, the `cloud` and the `url` keys.
+ * const cld = new Cloudinary({
+ *  // the cloudConfig
+ *  cloud: {
+ *       cloudName: 'demo'
+ *   },
+ *   // the urlConfig
+ *   url: {
+ *       cname: 'www.example.com',
+ *       forceVersion: true
+ *   }
+ * });
  */
 interface ICloudinaryAssetConfigurations {
   cloud?: ICloudConfig

src/config/interfaces/Config/ICloudinaryConfigurations.ts

@@ -6,6 +6,7 @@ import IApiConfig from "./IApiConfig";
  * @name ICloudinaryAssetConfigurations
  * @summary config
  * @description Defines the configuration needed for the Cloudinary Base SDK</br>
+ * @private
  *
  * @prop {IApiConfig} [api]
  * @prop {ITagConfig} [tag]

src/config/interfaces/Config/ITagConfig.ts

@@ -1,3 +1,7 @@
+/**
+ * @description - Not currently in use
+ * @private
+ */
 interface ITagConfig {
   hiDpi?: boolean;
   clientHints?: boolean;

src/config/interfaces/Config/IURLConfig.ts

@@ -2,8 +2,9 @@
  * @name ICloudinaryAssetConfigurations
  * @summary config
  * @description Defines the configuration needed for URL-related options when creating Cloudinary URL
+ * <b>Learn more:</b> {@link https://cloudinary.com/documentation/cloudinary_sdks#configuration_parameters|URL Parameters}
  * @prop {string}  [cname]
- * @prop {boolean} [secureDistribution]
+ * @prop {string} [secureDistribution]
  * @prop {boolean} [privateCdn]
  * @prop {boolean} [signUrl]
  * @prop {boolean} [longUrlSignature]
@@ -12,6 +13,20 @@
  * @prop {boolean} [secure]
  * @prop {boolean} [forceVersion]
  * @prop {boolean} [analytics]
+ * @example
+ * import Cloudinary from '@cloudinary/base';
+ * // The Cloudinary Instance accepts a URLConfig under the `url` key
+ * const cld = new Cloudinary({
+ *  // the cloudConfig
+ *  cloud: {
+ *       cloudName: 'demo'
+ *   },
+ *   // the urlConfig
+ *   url: {
+ *       cname: 'www.example.com',
+ *       forceVersion: true
+ *   }
+ * });
  */
 interface IURLConfig {
   /**
@@ -32,7 +47,7 @@ interface IURLConfig {
    *
    * https://{cname|secureDistribution}/image/upload
    * instead of
-   * * https://{cname|secureDistribution}/{cloudName}image/upload
+   * https://{cname|secureDistribution}/{cloudName}image/upload
    *
    * When privateCdn is provided without cname or secure distribution,
    * it moves the cloudName from the URL to the domain:
@@ -54,10 +69,29 @@ interface IURLConfig {
    */
   analytics?: boolean;
 
+  /**
+   * Whether or not to sign the URL
+   */
   signUrl?: boolean;
+
+  /**
+   * Whether or not to use a long signature
+   */
   longUrlSignature?: boolean;
+
+  /**
+   * Whether or not to shorten the URL
+   */
   shorten?: boolean;
+
+  /**
+   * Whether or not to use the root path
+   */
   useRootPath?: boolean;
+
+  /**
+   * Whether or not to force a version
+   */
   forceVersion?: boolean;
 }