Add links to qualifiers (#377)

patrick-tolosa · web-flow · commit 21d5312d3544 · 2021-04-08T12:14:59.000+03:00
diff --git a/src/actions/effect.ts b/src/actions/effect.ts
@@ -457,6 +457,8 @@ function theme(color: SystemColors): ThemeEffect {
  * import {Cloudinary} from "@cloudinary/base";
  * // Import everything, or just the action you need for tree-shaking purposes
  * import {Effect, sepia} from "@cloudinary/base/actions/effect";
+ * import {ArtisticFilter, alDente} from "../../../src/qualifiers/artisticFilter";
+ * import {ShakeStrength, pixels16} from "../../../src/qualifiers/shakeStrength";
  *
  * const yourCldInstance = new Cloudinary({cloud:{cloudName:'demo'}});
  * const image = yourCldInstance.image('woman');
@@ -495,7 +497,8 @@ function theme(color: SystemColors): ThemeEffect {
  * .effect(Effect.vignette().strength(5))
  * .effect(Effect.deshake())
  * .effect(Effect.deshake(10))
- * .effect(Effect.deshake().shakeStrength(ShakeStrength.pixels16()))
+ * .effect(Effect.artisticFilter(alDente())
+ * .effect(Effect.deshake().shakeStrength(pixels16()))
  */
 const Effect = {
   pixelate: pixelate,
diff --git a/src/qualifiers/FontAntialias.ts b/src/qualifiers/FontAntialias.ts
@@ -4,6 +4,7 @@
  * <b>Learn more</b>: {@link https://cloudinary.com/documentation/video_manipulation_and_delivery#adding_text_captions | Adding text overlays to videos}
  * @memberOf Qualifiers
  * @namespace FontAntialias
+ * @see To be used with {@link Qualifiers.TextStyle|Text Style}
  */
 
 /**
diff --git a/src/qualifiers/animatedFormat.ts b/src/qualifiers/animatedFormat.ts
@@ -4,6 +4,7 @@ import {AnimatedFormatQualifierValue} from "./animatedFormat/AnimatedFormatQuali
  * @description Contains methods to specify the animated format
  * @namespace AnimatedFormat
  * @memberOf Qualifiers
+ * @see Visit {@link Actions.Transcode|Transcode} for an example
  */
 
 
diff --git a/src/qualifiers/artisticFilter.ts b/src/qualifiers/artisticFilter.ts
@@ -3,6 +3,7 @@
  * Learn more: {@link https://cloudinary.com/documentation/image_transformations#artistic_filter_effects | Custom functions}
  * @namespace ArtisticFilter
  * @memberOf Qualifiers
+ * @see Visit {@link Actions.Effect|Effect} for an example
  */
 
 
diff --git a/src/qualifiers/aspectRatio.ts b/src/qualifiers/aspectRatio.ts
@@ -79,6 +79,7 @@ function ignoreInitialAspectRatio(): FlagQualifier {
  * This is used in the context of resize actions
  * @namespace AspectRatio
  * @memberOf Qualifiers
+ * @see Visit {@link Actions.Resize|Resize} for an example
  */
 const AspectRatio = {
   ar1X1,
diff --git a/src/qualifiers/audioCodec.ts b/src/qualifiers/audioCodec.ts
@@ -2,6 +2,7 @@
  * @description Contains functions to select an audio codec.
  * @memberOf Qualifiers
  * @namespace AudioCodec
+ * @see Visit {@link Actions.Transcode|Transcode} for an example
  */
 
 /**
diff --git a/src/qualifiers/audioFrequency.ts b/src/qualifiers/audioFrequency.ts
@@ -2,6 +2,7 @@
  * @description Controls the audio sampling frequency.
  * @namespace AudioFrequency
  * @memberOf Qualifiers
+ * @see Visit {@link Actions.Transcode|Transcode} for an example
  */
 
 
diff --git a/src/qualifiers/autoFocus.ts b/src/qualifiers/autoFocus.ts
@@ -1,35 +1,36 @@
 import {QualifierValue} from "../internal/qualifier/QualifierValue";
 import {FocusOnValue} from "./focusOn";
 
-
-/**
- * Accepts an AutoFocusObject (which is just a wrapper for a FocusOn object, but with extra method: avoid, weight)
- * @param {AutoFocus} AutoFocusObjects
- */
-
 /**
  * @summary qualifier
- * @description A wrapper class around a FocusOn object.
  * @namespace AutoFocus
  * @memberOf Qualifiers
+ * @see Visit {@link Qualifiers.Gravity|Gravity} for an example
+ */
+
+
+/**
+ * @memberOf Qualifiers.AutoFocus
  * @extends {SDK.QualifierValue}
+ * @see Visit {@link Qualifiers.Gravity|Gravity} for an example
  */
 class AutoFocus extends QualifierValue {
-  readonly focusOn:FocusOnValue;
+  readonly focusOn: FocusOnValue;
   private _weight: number | string;
-  private shouldAvoid:boolean;
+  private shouldAvoid: boolean;
 
   /**
- * @summary qualifier
- * @description Specifies the object to focus on automatically
+   * @summary qualifier
+   * @description Specifies the object to focus on automatically
+   * Accepts an AutoFocusObject (which is just a wrapper for a FocusOn object, but with extra method: avoid, weight)
    * @param {Qualifiers.FocusOn} obj The object to focus on.
    * @param {number} weight
    */
   static focusOn(obj: FocusOnValue, weight?: number): AutoFocus {
     return new AutoFocus(obj, weight);
   }
 
-  constructor(focusOn:FocusOnValue, weight?: number | string) {
+  constructor(focusOn: FocusOnValue, weight?: number | string) {
     super();
     this._weight = weight;
     this.focusOn = focusOn;
@@ -41,18 +42,18 @@ class AutoFocus extends QualifierValue {
   }
 
   /**
- * @summary qualifier
- * @desc Get the name of the of the object
+   * @summary qualifier
+   * @desc Get the name of the of the object
    */
-  private getName():string {
+  private getName(): string {
     return this.focusOn.name;
   }
 
   /**
- * @summary qualifier
- * @desc Get the weight for the object
+   * @summary qualifier
+   * @desc Get the weight for the object
    */
-  private getWeight():number|string {
+  private getWeight(): number | string {
     if (this.shouldAvoid) {
       return 'avoid';
     } else {
@@ -61,21 +62,21 @@ class AutoFocus extends QualifierValue {
   }
 
   /**
- * @summary qualifier
- * @desc Return the string representation of this QualifierValue
+   * @summary qualifier
+   * @desc Return the string representation of this QualifierValue
    */
-  toString():string {
+  toString(): string {
     // Future proofing, in case we'd like to support some custom string in the future, or if data is coming from a DB
-    if(this.shouldAddWeight()) {
+    if (this.shouldAddWeight()) {
       return `${this.getName()}_${this.getWeight()}`;
     } else {
       return `${this.getName()}`;
     }
   }
 
   /**
- * @summary qualifier
- * @description Sets the importance level of the object within the automatic gravity algorithm
+   * @summary qualifier
+   * @description Sets the importance level of the object within the automatic gravity algorithm
    * @param {numebr} w The focus weight for the object
    * @return {this}
    */
@@ -85,8 +86,8 @@ class AutoFocus extends QualifierValue {
   }
 
   /**
- * @summary qualifier
- * @description Attempts to avoid the detected object in the image
+   * @summary qualifier
+   * @description Attempts to avoid the detected object in the image
    * @return {this}
    */
   avoid(): this {
diff --git a/src/qualifiers/blendMode.ts b/src/qualifiers/blendMode.ts
@@ -5,6 +5,7 @@ import {BlendModeQualifier} from "./blendMode/BlendModeQualifier";
  * <b>Learn more:</b> {@link https://cloudinary.com/documentation/image_transformations#overlay_blending_effects|Overlay blending effects}
  * @namespace BlendMode
  * @memberOf Qualifiers
+ * @see To be used with an {@link Actions.Overlay|Overlay}
  */
 
 
diff --git a/src/qualifiers/chromaSubSampling.ts b/src/qualifiers/chromaSubSampling.ts
@@ -17,6 +17,8 @@ function chroma420():number { return 420; }
  * <b>Learn more</b>: {@link https://cloudinary.com/documentation/image_transformations#toggling_chroma_subsampling | Toggling chroma subsampling}
  * @memberOf Qualifiers
  * @namespace ChromeSubSampling
+ * @see To be used in {@link Actions.Delivery|Delivery} action (Quality)
+ * @see To be used in {@link Actions.Delivery.DeliveryQualityAction|Quality Action} class
  */
 const ChromaSubSampling = {
   chroma444,
diff --git a/src/qualifiers/color.ts b/src/qualifiers/color.ts
@@ -1,7 +1,14 @@
 /**
  * @memberOf Qualifiers
+ * @description This namespace contains all the colors used in the SDK
  * @namespace Color
+ * @example
+ * // Reference only, do NOT use within your code for tree-shaking reasons
+ * // SDK functions that require color accept a string (like 'red') or a hex value, like 'ffffff'
+ * import {Color} from '@cloudinary/base/qualifiers/color'
+ * console.log(Color.RED);
  */
+
 const Color = {
   SNOW:'snow',
   SNOW1:'snow1',
diff --git a/src/qualifiers/colorSpace.ts b/src/qualifiers/colorSpace.ts
@@ -2,6 +2,7 @@
  * @description Contains functions to select the color space mode.
  * @namespace ColorSpace
  * @memberOf Qualifiers
+ * @see Visit {@link Actions.Delivery.colorSpace|Delivery Color Space} for an example
  */
 
 /**
diff --git a/src/qualifiers/compass.ts b/src/qualifiers/compass.ts
@@ -98,6 +98,7 @@ function center(): CompassQualifier {
  * @description Defines the focal Compass for certain methods of cropping.
  * @namespace Compass
  * @memberOf Qualifiers
+ * @see Visit {@link Qualifiers.Gravity|Gravity} for an example
  */
 class Compass {
   static north = north;
diff --git a/src/qualifiers/concatenate.ts b/src/qualifiers/concatenate.ts
@@ -5,6 +5,7 @@ import {FetchSource} from "./source/sourceTypes/FetchSource";
  * @description This namespace contains different sources that can be used when concatenating to a video
  * @memberOf Qualifiers
  * @namespace Concatenate
+ * @see Visit {@link Actions.VideoEdit.concatenate|VideoEdit.concatenate} for an example
  */
 
 
diff --git a/src/qualifiers/dither.ts b/src/qualifiers/dither.ts
@@ -2,6 +2,7 @@
  * @description Qualifiers for applying an ordered dither filter to the image.
  * @namespace Dither
  * @memberOf Qualifiers
+ * @see Visit {@link Actions.Effect.dither|Dither Effect} for an example
  */
 
 
diff --git a/src/qualifiers/dpr.ts b/src/qualifiers/dpr.ts
@@ -3,6 +3,7 @@
  * <b>Learn more</b>: {@link https://cloudinary.com/documentation/image_transformations#set_device_pixel_ratio_dpr | Set Device Pixel Ratio}
  * @memberOf Qualifiers
  * @namespace DPR
+ * @see Visit {@link Actions.Delivery.dpr|Delivery DPR} for an example
  */
 
 /**
diff --git a/src/qualifiers/focusOn.ts b/src/qualifiers/focusOn.ts
@@ -290,6 +290,7 @@ function tvmonitor(): FocusOnValue {
 /**
  * @memberOf Qualifiers
  * @namespace FocusOn
+ * @see Visit {@link Qualifiers.Gravity|Gravity} for an example
  */
 const FocusOn = {
   person,
diff --git a/src/qualifiers/fontHinting.ts b/src/qualifiers/fontHinting.ts
@@ -4,6 +4,7 @@
  * <b>Learn more</b>: {@link https://cloudinary.com/documentation/video_manipulation_and_delivery#adding_text_captions | Adding text overlays to videos}
  * @memberOf Qualifiers
  * @namespace FontHinting
+ * @see To be used with {@link Qualifiers.TextStyle|Text Style}
  */
 
 
diff --git a/src/qualifiers/fontStyle.ts b/src/qualifiers/fontStyle.ts
@@ -4,6 +4,7 @@
  * <b>Learn more</b>: {@link https://cloudinary.com/documentation/video_manipulation_and_delivery#adding_text_captions | Adding text overlays to videos}
  * @memberOf Qualifiers
  * @namespace FontStyle
+ * @see To be used with {@link Qualifiers.TextStyle|Text Style}
  */
 
 /**
diff --git a/src/qualifiers/fontWeight.ts b/src/qualifiers/fontWeight.ts
@@ -4,6 +4,7 @@
  * <b>Learn more</b>: {@link https://cloudinary.com/documentation/video_manipulation_and_delivery#adding_text_captions | Adding text overlays to videos}
  * @memberOf Qualifiers
  * @namespace FontWeight
+ * @see To be used with {@link Qualifiers.TextStyle|Text Style}
  */
 
 /**
diff --git a/src/qualifiers/format.ts b/src/qualifiers/format.ts
@@ -4,8 +4,7 @@ import {FormatQualifier} from "./format/FormatQualifier";
  * @description Contains functions to select the asset format, can be used to convert images and videos to other formats.
  * @memberOf Qualifiers
  * @namespace Format
- * @example
- * transformation.delivery(Delivery.format(Format.jpg()))
+ * @see Visit {@link Actions.Delivery.format|Delivery Format} for an example
  */
 
 
diff --git a/src/qualifiers/gravity.ts b/src/qualifiers/gravity.ts
@@ -116,6 +116,8 @@ function xyCenter(): XYCenterGravity {
  * const yourCldInstance = new Cloudinary({cloud: {cloudName: 'demo'}});
  * const image = yourCldInstance.image('woman');
  * image.resize(crop().width(300).gravity(compass(north())))
+ *
+ * // Expand every function separately to see its own example
  */
 const Gravity = {
   compass: compass,
diff --git a/src/qualifiers/improveMode.ts b/src/qualifiers/improveMode.ts
@@ -3,6 +3,15 @@
  * @description Defines the available modes to use with the improve effect.
  * @namespace ImproveMode
  * @memberOf Qualifiers
+ * @see To be used with an {@link Actions.Adjust.improve|Adjust Improve}
+ * @example
+ * import {Cloudinary} from "@cloudinary/base/instance/Cloudinary";
+ * import {outdoor} from "@cloudinary/base/qualifiers/improveMode";
+ * import {improve} from "@cloudinary/base/actions/adjust";
+ *
+ * const yourCldInstance = new Cloudinary({cloud: {cloudName: 'demo'}});
+ * const image = yourCldInstance.image('woman');
+ * image.adjust(improve().mode(outdoor()));
  */
 
 
diff --git a/src/qualifiers/outlineMode.ts b/src/qualifiers/outlineMode.ts
@@ -2,14 +2,7 @@
  * @description Contains functions to select the type of improvement to perform when using Adjust.improve().
  * @namespace Outline
  * @memberOf Qualifiers
- * @example
- * import {Cloudinary} from "@cloudinary/base";
- * import {outdoor} from "@cloudinary/base/qualifiers/improveMode";
- * import {improve} from "@cloudinary/base/actions/adjust";
- *
- * const yourCldInstance = new Cloudinary({cloud: {cloudName: 'demo'}});
- * const image = yourCldInstance.image('woman');
- * image.adjust(improve().mode(outdoor()));
+ * @see Visit {@link Actions.Effect|Effect Action} for an example
  */
 
 /**
diff --git a/src/qualifiers/position.ts b/src/qualifiers/position.ts
@@ -6,6 +6,8 @@ import {PositionQualifier} from "./position/PositionQualifier";
  * <b>Learn more:</b> {@link https://cloudinary.com/documentation/image_transformations#image_and_text_overlays|Applying overlays to images} | {@link https://cloudinary.com/documentation/video_manipulation_and_delivery#adding_image_overlays|Applying overlays to videos}
  * @namespace Position
  * @memberOf Qualifiers
+ * @see {@link Actions.Overlay| The overlay action}
+ * @see {@link Actions.Underlay| The underlay action}
  *
  */
 export {
diff --git a/src/qualifiers/quality.ts b/src/qualifiers/quality.ts
@@ -1,6 +1,7 @@
 /**
  * @memberOf Qualifiers
  * @namespace Quality
+ * @see Visit {@link Actions.Delivery.quality|Delivery Quality} for an example
  */
 
 /**
diff --git a/src/qualifiers/rotationMode.ts b/src/qualifiers/rotationMode.ts
@@ -5,6 +5,7 @@
  * </br><b>Learn more</b>: {@link https://cloudinary.com/documentation/video_manipulation_and_delivery#rotating_videos | Rotating videos}
  * @memberOf Qualifiers
  * @namespace RotationMode
+ * @see Visit {@link Actions.Rotate|Rotate Action} for an example
  */
 
 
diff --git a/src/qualifiers/shakeStrength.ts b/src/qualifiers/shakeStrength.ts
@@ -2,6 +2,7 @@
  * @description Contains functions to select the maximum number of pixels in the horizontal and vertical direction that are addressed.
  * @memberOf Qualifiers
  * @namespace ShakeStrength
+ * @see Visit {@link Actions.Effect|Effect} for an example
  */
 
 /**
diff --git a/src/qualifiers/simulateColorBlind.ts b/src/qualifiers/simulateColorBlind.ts
@@ -3,6 +3,7 @@
  * <b>Learn more</b>: {@link https://cloudinary.com/blog/open_your_eyes_to_color_accessibility | Blog: Open your Eyes to Color Accessibility}
  * @memberOf Qualifiers
  * @namespace SimulateColorBlindValues
+ * @see Visit {@link Actions.Effect|Effect} for an example
  */
 
 /**
diff --git a/src/qualifiers/source.ts b/src/qualifiers/source.ts
@@ -9,6 +9,8 @@ import {TextSource} from "./source/sourceTypes/TextSource";
  * @description This namespace contains different sources that can be used in overlays and underlays
  * @memberOf Qualifiers
  * @namespace Source
+ * @see {@link Actions.Overlay| The overlay action}
+ * @see {@link Actions.Underlay| The underlay action}
  */
 
 
diff --git a/src/qualifiers/streamingProfile.ts b/src/qualifiers/streamingProfile.ts
@@ -2,6 +2,7 @@
  * @description Qualifiers for applying an ordered dither filter to the image.
  * @namespace StreamingProfile
  * @memberOf Qualifiers
+ * @see Visit {@link Actions
  */
 
 
diff --git a/src/qualifiers/textAlignment.ts b/src/qualifiers/textAlignment.ts
diff --git a/src/qualifiers/textDecoration.ts b/src/qualifiers/textDecoration.ts
diff --git a/src/qualifiers/timeline.ts b/src/qualifiers/timeline.ts
diff --git a/src/qualifiers/transition.ts b/src/qualifiers/transition.ts
diff --git a/src/qualifiers/videoCodec.ts b/src/qualifiers/videoCodec.ts
diff --git a/src/qualifiers/videoCodecLevel.ts b/src/qualifiers/videoCodecLevel.ts
diff --git a/src/qualifiers/videoCodecProfile.ts b/src/qualifiers/videoCodecProfile.ts
diff --git a/src/qualifiers/volume.ts b/src/qualifiers/volume.ts
