Add better docs to Reshape (#370)

patrick-tolosa · web-flow · commit 2478c38ad5c4 · 2021-04-05T10:49:09.000+03:00
* Add better docs to Reshape
diff --git a/src/actions/delivery/DeliveryAction.ts b/src/actions/delivery/DeliveryAction.ts
@@ -5,7 +5,7 @@ import {Qualifier} from "../../internal/qualifier/Qualifier";
 /**
  * @description Qualifies the delivery of an asset.
  * @memberOf Actions.Delivery
- * @extends {SDK.Action}
+ * @extends SDK.Action
  */
 class DeliveryAction extends Action {
 
diff --git a/src/actions/delivery/DeliveryColorSpaceFromICC.ts b/src/actions/delivery/DeliveryColorSpaceFromICC.ts
@@ -6,7 +6,7 @@ import {Qualifier} from "../../internal/qualifier/Qualifier";
 /**
  * @description Specifies the ICC profile to use for the color space.
  * @memberOf Actions.Delivery
- * @extends {SDK.Action}
+ * @extends SDK.Action
  * @see Visit {@link Actions.Delivery|Delivery} for an example
  */
 class DeliveryColorSpaceFromICC extends Action {
diff --git a/src/actions/effect/EffectActions/SimpleEffectAction.ts b/src/actions/effect/EffectActions/SimpleEffectAction.ts
@@ -5,7 +5,7 @@ import {ExpressionQualifier} from "../../../qualifiers/expression/ExpressionQual
 
 /**
  * @description A class that defines a simple effect of the type e_{effectName}
- * @extends {SDK.Action}
+ * @extends SDK.Action
  * @memberOf Actions.Effect
  * @see Visit {@link Actions.Effect|Effect} for an example
  */
diff --git a/src/actions/effect/blur/blur.ts b/src/actions/effect/blur/blur.ts
@@ -4,7 +4,7 @@ import {Action} from "../../../internal/Action";
 
 /**
  * @description The Action class of the blur Builder.
- * @extends {SDK.Action}
+ * @extends SDK.Action
  * @memberOf Actions.Effect
  * @see Visit {@link Actions.Effect|Effect} for an example
  */
diff --git a/src/actions/effect/pixelate/pixelate.ts b/src/actions/effect/pixelate/pixelate.ts
@@ -4,7 +4,7 @@ import {Action} from "../../../internal/Action";
 
 /**
  * @description The Action class of the pixelate Builder
- * @extends {SDK.Action}
+ * @extends SDK.Action
  * @memberOf Actions.Effect
  * @see Visit {@link Actions.Effect|Effect} for an example
  */
diff --git a/src/actions/layer/LayerAction.ts b/src/actions/layer/LayerAction.ts
@@ -8,7 +8,7 @@ import {BaseSource} from "../../qualifiers/source/BaseSource";
 
 
 /**
- * @extends {SDK.Action}
+ * @extends SDK.Action
  * @memberOf SDK
  * @description
  * A generic Layer action that can add a Video, Text or Image layer.<br>
diff --git a/src/actions/namedTransformation/NamedTransformationAction.ts b/src/actions/namedTransformation/NamedTransformationAction.ts
@@ -3,7 +3,7 @@ import {Qualifier} from "../../internal/qualifier/Qualifier";
 
 /**
  * @description Applies a pre-defined named transformation of the given name, used with a builder from {@link Actions.NamedTransformation|Named Transformation}
- * @extends {SDK.Action}
+ * @extends SDK.Action
  * @memberOf Actions.NamedTransformation
  * @see Visit {@link Actions.NamedTransformation|Named Transformation} for an example
  */
diff --git a/src/actions/psdTools/ClipAction.ts b/src/actions/psdTools/ClipAction.ts
@@ -5,7 +5,7 @@ import {clip, clipEvenOdd} from "../../qualifiers/flag";
 
 /**
  * @description  Defines the clipping path to use when trimming pixels.
- * @extends {SDK.Action}
+ * @extends SDK.Action
  * @memberOf Actions.PSDTools
  * @see Visit {@link Actions.PSDTools| PSDTools} for an example
  */
diff --git a/src/actions/psdTools/GetLayerAction.ts b/src/actions/psdTools/GetLayerAction.ts
@@ -5,7 +5,7 @@ import {QualifierValue} from "../../internal/qualifier/QualifierValue";
 /**
  * @description Represents a layer in a Photoshop document.
  * </br><b>Learn more:</b> {@link https://cloudinary.com/documentation/paged_and_layered_media#deliver_selected_layers_of_a_psd_image | Deliver selected layers of a PSD image}
- * @extends {SDK.Action}
+ * @extends SDK.Action
  * @memberOf Actions.PSDTools
  * @see Visit {@link Actions.PSDTools| PSDTools} for an example
  */
diff --git a/src/actions/psdTools/SmartObjectAction.ts b/src/actions/psdTools/SmartObjectAction.ts
@@ -5,7 +5,7 @@ import {QualifierValue} from "../../internal/qualifier/QualifierValue";
 /**
  * @description Represents an embedded smart object in a Photoshop document.
  * </br><b>Learn more:</b> {@link https://cloudinary.com/documentation/paged_and_layered_media#extract_the_original_content_of_an_embedded_object | Extract the original content of an embedded Photoshop object}
- * @extends {SDK.Action}
+ * @extends SDK.Action
  * @memberOf Actions.PSDTools
  * @see Visit {@link Actions.PSDTools| PSDTools} for an example
  */
diff --git a/src/actions/reshape.ts b/src/actions/reshape.ts
@@ -13,6 +13,8 @@ type IReshape = CutByImage | DistortArcAction;
  * @namespace Reshape
  * @description Adjusts the shape of the delivered image. </br>
  * <b>Learn more:</b> {@link https://cloudinary.com/documentation/image_transformations#image_shape_changes_and_distortion_effects|Shape changes and distortion effects}
+ * @example
+ * // Expand every function separately to see its own example
  */
 
 
@@ -23,6 +25,22 @@ type IReshape = CutByImage | DistortArcAction;
  * Wherever the overlay image is transparent, the original is shown, and wherever the overlay is opaque, the resulting image is transparent.
  * @param {Qualifiers.Source.ImageSource} imageSource
  * @memberOf Actions.Reshape
+ * @return {Actions.Reshape.CutByImage}
+ * @example
+ * <caption> <h4>Cut an image by using another image(Gravity)</h4> </caption>
+ * import {Cloudinary, Transformation} from "@cloudinary/base";
+ *
+ * const yourCldInstance = new Cloudinary({cloud:{cloudName:'demo'}});
+ * const img = yourCldInstance.image('woman');
+ *
+ * import {cutByImage} from '@cloudinary/base/actions/reshape';
+ * import {image} from "@cloudinary/base/qualifiers/source";
+ *
+ * img.reshape(
+ *    cutByImage(
+ *        image('sourceImage').transformation(new Transformation())
+ * ))
+ * img.toURL()
  */
 function cutByImage(imageSource: ImageSource): CutByImage {
   return new CutByImage(imageSource);
@@ -37,6 +55,20 @@ function cutByImage(imageSource: ImageSource): CutByImage {
  *
  * @param {number} degrees The degrees to arc the image
  * @memberOf Actions.Reshape
+ * @return {Actions.Reshape.DistortArcAction}
+ * @example
+ * <caption> <h4>Distort arc</h4> </caption>
+ * import {Cloudinary, Transformation} from "@cloudinary/base";
+ *
+ * const yourCldInstance = new Cloudinary({cloud:{cloudName:'demo'}});
+ * const img = yourCldInstance.image('woman');
+ *
+ * import {distortArc} from '@cloudinary/base/actions/reshape';
+ *
+ * img.reshape(
+ *    distortArc(200)
+ * )
+ * img.toURL()
  */
 function distortArc(degrees: number): DistortArcAction {
   return new DistortArcAction(degrees);
@@ -52,6 +84,20 @@ function distortArc(degrees: number): DistortArcAction {
  *
  * @param {number[]} coordinates - Four x/y pairs representing the new image corners
  * @memberOf Actions.Reshape
+ * @return {Actions.Reshape.DistortAction}
+ * @example
+ * <caption> <h4>Distorting an image</h4> </caption>
+ * import {Cloudinary, Transformation} from "@cloudinary/base";
+ *
+ * const yourCldInstance = new Cloudinary({cloud:{cloudName:'demo'}});
+ * const img = yourCldInstance.image('woman');
+ *
+ * import {distort} from '@cloudinary/base/actions/reshape';
+ *
+ * img.reshape(
+ *    distort([100, 100, 100, 200, 200, 200, 200, 100])
+ * )
+ * img.toURL()
  */
 function distort(coordinates: IDistortCoordinates): DistortAction {
   return new DistortAction(coordinates);
@@ -63,6 +109,20 @@ function distort(coordinates: IDistortCoordinates): DistortAction {
  * @param {number} x Skews the image according to the two specified values in degrees. (X and Y)
  * @param {number} y Skews the image according to the two specified values in degrees. (X and Y)
  * @memberOf Actions.Reshape
+ * @return {Actions.Reshape.ShearAction}
+ * @example
+ * <caption> <h4>Shearing an image</h4> </caption>
+ * import {Cloudinary, Transformation} from "@cloudinary/base";
+ *
+ * const yourCldInstance = new Cloudinary({cloud:{cloudName:'demo'}});
+ * const img = yourCldInstance.image('woman');
+ *
+ * import {shear} from '@cloudinary/base/actions/reshape';
+ *
+ * img.reshape(
+ *    shear(50, 0)
+ * )
+ * img.toURL()
  */
 function shear(x: number, y: number): ShearAction {
   return new ShearAction(x, y);
@@ -74,6 +134,19 @@ function shear(x: number, y: number): ShearAction {
  * Specify a color other than the color of the corner pixels using the colorOverride() method
  * @memberOf Actions.Reshape
  * @return {Actions.Reshape.TrimAction}
+ * @example
+ * <caption> <h4>Trimming an image</h4> </caption>
+ * import {Cloudinary, Transformation} from "@cloudinary/base";
+ *
+ * const yourCldInstance = new Cloudinary({cloud:{cloudName:'demo'}});
+ * const img = yourCldInstance.image('woman');
+ *
+ * import {trim} from '@cloudinary/base/actions/reshape';
+ *
+ * img.reshape(
+ *    trim().colorOverride('blue').colorSimilarity(15)
+ * )
+ * img.toURL()
  */
 function trim(): TrimAction {
   return new TrimAction();
diff --git a/src/actions/reshape/CutByImage.ts b/src/actions/reshape/CutByImage.ts
@@ -7,9 +7,10 @@ import {Qualifier} from "../../internal/qualifier/Qualifier";
 /**
  * @description Trims pixels according to the transparency levels of a given overlay image.
  * Wherever the overlay image is transparent, the original is shown, and wherever the overlay is opaque, the resulting image is transparent.
- * @memberOf Actions.Reshape
+ * @extends SDK.Action
  * @param {Qualifiers.Source.ImageSource} imageSource
- * @augments {SDK.Action}
+ * @memberOf Actions.Reshape
+ * @see Visit {@link Actions.Reshape| Reshape} for examples
  */
 class CutByImage extends Action {
   private source: ImageSource;
diff --git a/src/actions/reshape/Distort.ts b/src/actions/reshape/Distort.ts
@@ -10,9 +10,10 @@ export type IDistortCoordinates = [number, number, number, number, number, numbe
  * in clockwise order from the top-left corner.
  *
  * <b>Learn more:</b> {@link https://cloudinary.com/documentation/transformation_reference#e_distort | Distorting images}
- * @memberOf Actions.Reshape
  * @param {number[]} coordinates - Four x/y pairs representing the new image corners
- * @extends {SDK.Action}
+ * @extends SDK.Action
+ * @memberOf Actions.Reshape
+ * @see Visit {@link Actions.Reshape| Reshape} for examples
  */
 class DistortAction extends Action {
   constructor(coordinates: IDistortCoordinates) {
diff --git a/src/actions/reshape/DistortArc.ts b/src/actions/reshape/DistortArc.ts
@@ -6,9 +6,10 @@ import {Qualifier} from "../../internal/qualifier/Qualifier";
  *
  * <b>Learn more:</b> {@link https://cloudinary.com/documentation/transformation_reference#e_distort | Distorting images}</br>
  * <b>Learn more:</b> {@link https://cloudinary.com/documentation/image_transformations#image_shape_changes_and_distortion_effects | Distortion effects}
- * @memberOf Actions.Reshape
  * @param {number} degrees The degrees to arc the image
- * @extends {SDK.Action}
+ * @extends SDK.Action
+ * @memberOf Actions.Reshape
+ * @see Visit {@link Actions.Reshape| Reshape} for examples
  */
 class DistortArcAction extends Action {
   constructor(degrees: number) {
diff --git a/src/actions/reshape/Shear.ts b/src/actions/reshape/Shear.ts
@@ -2,8 +2,9 @@ import {Action} from "../../internal/Action";
 
 /**
  * @description Skews the image according to the two specified values in degrees.
+ * @extends SDK.Action
  * @memberOf Actions.Reshape
- * @extends {SDK.Action}
+ * @see Visit {@link Actions.Reshape| Reshape} for examples
  */
 class ShearAction extends Action {
   private _x: number;
diff --git a/src/actions/reshape/TrimAction.ts b/src/actions/reshape/TrimAction.ts
@@ -4,8 +4,9 @@ import {SystemColors} from "../../qualifiers/color";
 /**
  * @description Removes the edges of the image based on the color of the corner pixels.
  * Specify a color other than the color of the corner pixels using the colorOverride() method
+ * @extends SDK.Action
  * @memberOf Actions.Reshape
- * @extends {SDK.Action}
+ * @see Visit {@link Actions.Reshape| Reshape} for examples
  */
 class TrimAction extends Action {
   private _tolerance: number;
diff --git a/src/actions/resize.ts b/src/actions/resize.ts
@@ -36,8 +36,8 @@
  * const yourCldInstance = new Cloudinary({cloud:{cloudName:'demo'}});
  * const image = yourCldInstance.image('woman');
  *
- * const {scale} from '@cloudinary/base/actions/resize';
- * const {autoGravity} from '@cloudinary/base/qualifiers/gravity';
+ * import {scale} from '@cloudinary/base/actions/resize';
+ * import {autoGravity} from '@cloudinary/base/qualifiers/gravity';
  *
  * image.resize( crop(100, 100).gravity(autoGravity()) );
  *
diff --git a/src/actions/transcode/VideoCodecAction.ts b/src/actions/transcode/VideoCodecAction.ts
@@ -2,7 +2,7 @@ import {Action} from "../../internal/Action";
 import {AdvVideoCodecType, VideoCodecType} from "../../qualifiers/videoCodecType/VideoCodecType";
 
 /**
- * @extends {SDK.Action}
+ * @extends SDK.Action
  * @memberOf Actions.Transcode
  * @description Converts a video to an animated webp or gif.
  */
diff --git a/src/actions/variable/VariableAction.ts b/src/actions/variable/VariableAction.ts
@@ -8,7 +8,7 @@ type TypeVariableValue = number | string | ExpressionQualifier;
 /**
  * @description Defines an new user variable.
  * @memberOf Actions.Variable
- * @extends {SDK.Action}
+ * @extends SDK.Action
  */
 class VariableAction extends Action {
   private isFloat = false;
diff --git a/src/sdkAnalytics/getSDKAnalyticsSignature.ts b/src/sdkAnalytics/getSDKAnalyticsSignature.ts
@@ -21,8 +21,8 @@ function getNodeVersion() {
  * @private
  * @description Ensure that all values ITrackedPropertiesThroughAnalytics are populated.
  * Accept a partial map of values and returns the complete interface of ITrackedPropertiesThroughAnalytics
- * @param {Partial<ITrackedPropertiesThroughAnalytics>} trackedAnalytics
- * @param {Partial<ITrackedPropertiesThroughAnalytics>} trackedAnalytics
+ * @param {ITrackedPropertiesThroughAnalytics} trackedAnalytics
+ * @param {ITrackedPropertiesThroughAnalytics} trackedAnalytics
  */
 function ensureShapeOfTrackedProperties(trackedAnalytics?: Partial<ITrackedPropertiesThroughAnalytics>): ITrackedPropertiesThroughAnalytics {
   // try to get the process version from node, but if we're on the client return 0.0.0
@@ -85,7 +85,7 @@ export function getSDKAnalyticsSignature(_trackedAnalytics?: Partial<ITrackedPro
  * @private
  * @description Removes patch version from the semver if it exists
  *              Turns x.y.z OR x.y into x.y
- * @param {'x.y.z' || 'x.y' || string} semVerStr
+ * @param {'x.y.z' | 'x.y' | string} semVerStr
  */
 function removePatchFromSemver(semVerStr: string) {
   const parts = semVerStr.split('.');
