Update Javadocs of PdfCanvas#addXobject(PdfXObject, Rectangle) to mention scaling behavior. DEVSIX-2541

Author: michaeldemey

kernel/src/main/java/com/itextpdf/kernel/pdf/canvas/PdfCanvas.java

@@ -2014,9 +2014,13 @@ public PdfCanvas addXObject(PdfXObject xObject, float x, float y) {
 
     /**
      * Adds {@code PdfXObject} to specified rectangle on canvas.
+     * Do note that using this method of adding an XObject <b>will scale</b> the XObject using the width and the height
+     * of the provided Rectangle. If you don't wish to scale the XObject, use {@link PdfCanvas#addXObject(PdfXObject, float, float)},
+     * {@link PdfCanvas#addXObject(PdfXObject, float, float, float)}, {@link PdfCanvas#addXObject(PdfXObject, float, float, float, boolean)},
+     * or {@link PdfCanvas#addXObject(PdfXObject, float, float, float, float, float, float)}.
      *
-     * @param xObject
-     * @param rect
+     * @param xObject the XObject to add
+     * @param rect rectangle containing x and y coordinates and scaling information
      * @return current canvas.
      */
     public PdfCanvas addXObject(PdfXObject xObject, Rectangle rect) {
@@ -2288,10 +2292,10 @@ private PdfCanvas addForm(PdfFormXObject form, float x, float y) {
     }
 
     /**
-     * Adds {@code PdfFormXObject} to specified rectangle on canvas.
+     * Adds {@code PdfFormXObject} to specified rectangle on canvas and scale it using the rectangle's width and height.
      *
-     * @param form
-     * @param rect
+     * @param form PdfFormXObject to add
+     * @param rect rectangle containing x and y coordinates and scaling information
      * @return current canvas.
      */
     private PdfCanvas addForm(PdfFormXObject form, Rectangle rect) {
@@ -2378,10 +2382,10 @@ private PdfCanvas addImage(PdfImageXObject image, float x, float y) {
     }
 
     /**
-     * Adds {@code PdfImageXObject} to specified rectangle on canvas.
+     * Adds {@code PdfImageXObject} to specified rectangle on canvas and scale it using the rectangle's width and height.
      *
-     * @param image
-     * @param rect
+     * @param image PdfImageXObject to add
+     * @param rect rectangle containing x and y coordinates and scaling information
      * @return current canvas
      */
     private PdfCanvas addImage(PdfImageXObject image, Rectangle rect) {