Docs - Enhance inline examples in the codebase (#350)

Author: patrick-tolosa

__DOC_EXAMPLES__/annotatedExamples/configuration.md

@@ -1,4 +1,4 @@
-<h2>Global configuration (See {@link ICloudinaryConfigurations})</h2>
+<h2>1. Global configuration (See {@link ICloudinaryConfigurations})</h2>
 
 ```javascript
 // Import the cloudinary class
@@ -16,7 +16,7 @@ const cld = new Cloudinary({
 ```
 
 
-<h2>Instance configuration</h2>
+<h2>2. Instance configuration</h2>
 
 ```javascript
 
@@ -32,27 +32,3 @@ const image = new CloudinaryImage('sample', {
     secure: true // force https, set to false to force http
 });
 ```
-
-<h2>Asset Description (See {@link IDescriptor})</h2>
-
-```javascript
-// Import the cloudinary class
-import {Cloudinary} from "@cloudinary/base/instance/Cloudinary";
-
-// Create your instance
-const cld = new Cloudinary({
-    cloud: {
-        cloudName: 'demo'
-    },
-    url: {
-        secure: true // force https, set to false to force http
-    }
-});
-
-const myAsset = cld.video(); // or cld.image()
-
-myAsset.setPublicID('some-remote-url')
-myAsset.storageType = 'fetch';
-
-// https://res.cloudinary.com/video/fetch/some-remote-url
-```

__DOC_EXAMPLES__/annotatedExamples/imageOverlay.md

@@ -4,12 +4,12 @@ import {Cloudinary} from "@cloudinary/base/instance/Cloudinary";
 
 // Create your instance
 const cld = new Cloudinary({
-    cloud: {
-        cloudName: 'demo'
-    },
-    url: {
-        secure: true // force https, set to false to force http
-    }
+  cloud: {
+    cloudName: 'demo'
+  },
+  url: {
+    secure: true // force https, set to false to force http
+  }
 });
 
 // Lets create a new image
@@ -23,7 +23,7 @@ import {image} from "@cloudinary/base/qualifiers/source";
 
 // Import how to position your layer
 import {Position} from "@cloudinary/base/qualifiers/position";
-import {southEast} from "@cloudinary/base/qualifiers/gravity/qualifiers/compass/Compass";
+import {southEast} from "@cloudinary/base/qualifiers/compass";
 import {compass} from "@cloudinary/base/qualifiers/gravity";
 
 // We'll also scale our overlay, we'll need this for later.
@@ -32,13 +32,13 @@ import {Transformation} from "@cloudinary/base/transformation/Transformation";
 
 
 myImage.overlay(
-    Overlay.source( // An overlay has a Source and a Position Qualifiers
-        image('cloudinary_icon') // Mandatory - Source
-            .transformation(new Transformation()
-                .resize(scale().width(300).height(300)) // A source can be transformed like an image
-            ))
-        .position(new Position().gravity(compass(southEast()))
-        ),
+  Overlay.source( // An overlay has a Source and a Position Qualifiers
+    image('cloudinary_icon') // Mandatory - Source
+      .transformation(new Transformation()
+        .resize(scale().width(300).height(300)) // A source can be transformed like an image
+      ))
+    .position(new Position().gravity(compass(southEast()))
+    ),
 )
 myImage.toURL();
 // http://res.cloudinary.com/demo/image/upload/l_cloudinary_icon/c_scale,h_300,w_300/fl_layer_apply,g_south_east/sample

__DOC_EXAMPLES__/gettingStarted/terminology.md

@@ -7,7 +7,7 @@
 import {Cloudinary} from "@cloudinary/base/instance/Cloudinary";
 import {Rotate} from "@cloudinary/base/actions/rotate";
 import {Resize} from "@cloudinary/base/actions/resize";
-import {RotationMode} from "@cloudinary/base/qualifiers/RotationMode";
+import {RotationMode} from "@cloudinary/base/qualifiers/rotationMode";
 
 // Create your instance
 const cld = new Cloudinary({

src/actions/overlay.ts

@@ -6,8 +6,12 @@ import {LayerAction} from "./layer/LayerAction";
  * @memberOf Actions
  * @namespace Overlay
  * @example
- * new CloudinaryImage('woman')
- *    .overlay(
+ * import {Cloudinary} from "@cloudinary/base/instance/Cloudinary";
+ *
+ * const yourCldInstance = new Cloudinary({cloud:{cloudName:'demo'}});
+ * const image = yourCldInstance.image('woman');
+ *
+ * image.overlay(
  *       Overlay.source(Source.image('sample'))
  *     )
  */

src/actions/rotate/mode.ts

@@ -9,7 +9,13 @@ import {RotationModeQualifierValue} from "../../qualifiers/rotate/RotationModeQu
  * For a list of supported rotation modes see {@link Qualifiers.rotationModeValues| types of rotation modes} for
  * possible values
  * @example
- * transformation.rotate(Rotate.mode(RotationMode.autoLeft());
+ * import {mode} from "@cloudinary/base/actions/rotate";
+ * import {RotationMode} from "@cloudinary/base/qualifiers/rotationMode";
+ *
+ * const yourCldInstance = new Cloudinary({cloud:{cloudName:'demo'}});
+ * const image = yourCldInstance.image('woman');
+ *
+ * image.rotate(mode(RotationMode.autoLeft());
  * @return {RotateAction}
  */
 function mode(rotationMode: RotationModeQualifierValue | string) :RotateAction {

src/actions/transcode.ts

@@ -139,6 +139,9 @@ function toAnimated(animatedFormat: AnimatedFormatQualifierValue | string): ToAn
  * import {vp9} from '@cloudinary/base/qualifiers/videoCodec'
  * import {videoCodec} from '@cloudinary/base/actions/transcode'
  *
+ * const yourCldInstance = new Cloudinary({cloud:{cloudName:'demo'}});
+ * const video = yourCldInstance.video('dog');
+ *
  * video.transcode( videoCodec( vp9() ) );
  * @return {Actions.Transcode.VideoCodecAction}
  */

src/actions/underlay.ts

@@ -9,8 +9,11 @@ import {FetchSource} from "../qualifiers/source/sourceTypes/FetchSource";
  * @namespace Underlay
  * @description Adds an image or a text layer as an underlay under the base layer. </br>
  * @example
- * new CloudinaryImage('woman')
- *    .underlay(
+ * import {Cloudinary} from "@cloudinary/base/instance/Cloudinary";
+ *
+ * const yourCldInstance = new Cloudinary({cloud:{cloudName:'demo'}});
+ * const image = yourCldInstance.image('woman');
+ * image.underlay(
  *       Underlay.source(Source.image('sample'))
  *     )
  */

src/actions/videoEdit/ConcatenateAction.ts

@@ -10,7 +10,15 @@ import {FetchSource} from "../../qualifiers/source/sourceTypes/FetchSource";
  * <b>Learn more</b>: {@link https://cloudinary.com/documentation/video_manipulation_and_delivery#concatenating_videos | Concatenating videos}
  * @extend {SDK.Action}
  * @example
- * new CloudinaryVideo('dog').videoEdit(
+ * import {Cloudinary} from "@cloudinary/base/instance/Cloudinary";
+ * import {VideoEdit} from "@cloudinary/base/actions/videoEdit";
+ * import {Concatenate} from "@cloudinary/base/qualifiers/concatenate";
+ * import {Transition} from "@cloudinary/base/qualifiers/transition";
+ *
+ * const yourCldInstance = new Cloudinary({cloud:{cloudName:'demo'}});
+ * const video = yourCldInstance.video('dog');
+ *
+ * video.videoEdit(
  *  VideoEdit.concatenate(Concatenate.videoSource('butterfly'))
  *  .transition(Transition.videoSource('myTransition')) // can be omitted
  *  .duration(5) // can be omitted

src/qualifiers/background/shared/base/BaseGradientBackground.ts

@@ -23,7 +23,6 @@ class BaseGradientBackground extends BaseCommonBackground {
   /**
    * @description Sets the direction for a background gradient fade effect.
    * @param {Qualifiers.GradientDirection | string} direction Use one of these functions provided by {@link Qualifiers.GradientDirection|GradientDirection}
-   * @example gradientDirection(GradientDirection.horizontal())
    * @return {this}
    */
   gradientDirection(direction: GradientDirectionQualifierValue): this {

src/qualifiers/gravity.ts

@@ -13,7 +13,15 @@ import {XYCenterGravity} from "./gravity/xyCenterGravity/XYCenterGravity";
  * <b>Learn more:</b> {@link https://cloudinary.com/documentation/image_transformations#control_gravity | Control gravity for videos}
  * @param {Qualifiers.Compass} direction A compass Values
  * @memberOf Qualifiers.Gravity
- * @example image.resize(Resize.crop().width(300).gravity(Gravity.compass(Compass.north())))
+ * @example
+ * import {Cloudinary} from "@cloudinary/base/instance/Cloudinary";
+ * import {compass} from "@cloudinary/base/qualifiers/gravity";
+ * import {north} from "@cloudinary/base/qualifiers/compass";
+ * import {crop} from "@cloudinary/base/actions/resize";
+ *
+ * const yourCldInstance = new Cloudinary({cloud: {cloudName: 'demo'}});
+ * const image = yourCldInstance.image('woman');
+ * image.resize(crop().width(300).gravity(compass(north())))
  * @return {CompassGravity}
  */
 function compass(direction: CompassQualifier): CompassGravity {
@@ -25,7 +33,15 @@ function compass(direction: CompassQualifier): CompassGravity {
  * @description Specifies what to focus on, for example: faces, objects, eyes, etc.
  * @param {...Qualifier.FocusOn} args One or more objects to focus on
  * @memberOf Qualifiers.Gravity
- * @example image.resize(Resize.crop().width(300).gravity(Gravity.focusOn(FocusOn.cat())))
+ * @example
+ * import {Cloudinary} from "@cloudinary/base/instance/Cloudinary";
+ * import {focusOn} from "@cloudinary/base/qualifiers/gravity";
+ * import {crop} from "@cloudinary/base/actions/resize";
+ * import {cat} from "@cloudinary/base/qualifiers/focusOn";
+ *
+ * const yourCldInstance = new Cloudinary({cloud: {cloudName: 'demo'}});
+ * const image = yourCldInstance.image('woman');
+ * image.resize(crop().width(300).gravity(focusOn(cat())))
  * @return {FocusOnGravity}
  */
 function focusOn(...args: FocusOnValue[]): FocusOnGravity {
@@ -39,8 +55,24 @@ function focusOn(...args: FocusOnValue[]): FocusOnGravity {
  * @description Automatically identifies the most interesting regions in the asset, can be qualified further by including what to focus on.
  * @memberOf Qualifiers.Gravity
  * @return {Qualifiers.Gravity.AutoGravity}
- * @example image.resize(Resize.crop().width(300).gravity(Gravity.autoGravity()))
- * @example image.resize(Resize.crop().width(300).gravity(Gravity.autoGravity().autoFocus(AutoFocus.focusOn(FocusOn.cat()))))
+ * @example
+ * import {Cloudinary} from "@cloudinary/base/instance/Cloudinary";
+ * import {autoGravity} from "@cloudinary/base/qualifiers/gravity";
+ * import {crop} from "@cloudinary/base/actions/resize";
+ *
+ * const yourCldInstance = new Cloudinary({cloud: {cloudName: 'demo'}});
+ * const image = yourCldInstance.image('woman');
+ * image.resize(crop().width(300).gravity(autoGravity()))
+ * @example
+ * import {Cloudinary} from "@cloudinary/base/instance/Cloudinary";
+ * import {autoGravity} from "@cloudinary/base/qualifiers/gravity";
+ * import {crop} from "@cloudinary/base/actions/resize";
+ * import {cat} from "@cloudinary/base/qualifiers/focusOn";
+ * import {AutoFocus} from "@cloudinary/base/qualifiers/autoFocus";
+ *
+ * const yourCldInstance = new Cloudinary({cloud: {cloudName: 'demo'}});
+ * const image = yourCldInstance.image('woman');
+ * image.resize(crop().width(300).gravity(autoGravity().autoFocus(AutoFocus.focusOn(cat()))))
  */
 function autoGravity(): AutoGravity {
   return new AutoGravity();
@@ -65,7 +97,7 @@ function ocr(): OCR {
  * @memberOf Qualifiers.Gravity
  * @return {XYCenterGravity}
  */
-function xyCenter() {
+function xyCenter(): XYCenterGravity {
   return new XYCenterGravity();
 }
 
@@ -76,7 +108,15 @@ function xyCenter() {
  *              when any part of the asset is cropped. For overlays, this setting determines where to place the overlay.
  * @namespace Gravity
  * @memberOf Qualifiers
- * @example image.resize(Resize.crop().width(300).gravity(Gravity.compass(Compass.north())))
+ * @example
+ * import {Cloudinary} from "@cloudinary/base/instance/Cloudinary";
+ * import {compass} from "@cloudinary/base/qualifiers/gravity";
+ * import {north} from "@cloudinary/base/qualifiers/compass";
+ * import {crop} from "@cloudinary/base/actions/resize";
+ *
+ * const yourCldInstance = new Cloudinary({cloud: {cloudName: 'demo'}});
+ * const image = yourCldInstance.image('woman');
+ * image.resize(crop().width(300).gravity(compass(north())))
  */
 const Gravity = {
   compass: compass,