From 5cd2641a99b822a6abc86f4bb03d0b5a3afa0c0e Mon Sep 17 00:00:00 2001
From: Oliver Vogel <oliver@olivervogel.com>
Date: Mon, 4 Mar 2024 16:48:36 +0100
Subject: [PATCH] Add doc block @link tags to main methods

---
 src/ImageManager.php              | 10 +++++
 src/Interfaces/ImageInterface.php | 67 +++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+)

diff --git a/src/ImageManager.php b/src/ImageManager.php
index 613a8998..46e9427a 100644
--- a/src/ImageManager.php
+++ b/src/ImageManager.php
@@ -15,6 +15,10 @@ final class ImageManager
 {
     protected DriverInterface $driver;
 
+    /**
+     * @link https://image.intervention.io/v3/basics/image-manager#create-a-new-image-manager-instance
+     * @param string|DriverInterface $driver
+     */
     public function __construct(string|DriverInterface $driver)
     {
         $this->driver = $this->resolveDriver($driver);
@@ -23,6 +27,7 @@ final class ImageManager
     /**
      * Create image mangager with given driver
      *
+     * @link https://image.intervention.io/v3/basics/image-manager
      * @param string|DriverInterface $driver
      * @return ImageManager
      */
@@ -34,6 +39,7 @@ final class ImageManager
     /**
      * Create image manager with GD driver
      *
+     * @link https://image.intervention.io/v3/basics/image-manager#static-gd-driver-constructor
      * @return ImageManager
      */
     public static function gd(): self
@@ -44,6 +50,7 @@ final class ImageManager
     /**
      * Create image manager with Imagick driver
      *
+     * @link https://image.intervention.io/v3/basics/image-manager#static-imagick-driver-constructor
      * @return ImageManager
      */
     public static function imagick(): self
@@ -54,6 +61,7 @@ final class ImageManager
     /**
      * Create new image instance with given width & height
      *
+     * @link https://image.intervention.io/v3/basics/instantiation#creating-new-images
      * @param int $width
      * @param int $height
      * @throws RuntimeException
@@ -87,6 +95,7 @@ final class ImageManager
      * If the second parameter is not set, an attempt to decode the input is made
      * with all available decoders of the driver.
      *
+     * @link https://image.intervention.io/v3/basics/instantiation#reading-images
      * @param mixed $input
      * @param string|array|DecoderInterface $decoders
      * @throws RuntimeException
@@ -106,6 +115,7 @@ final class ImageManager
     /**
      * Create new animated image by given callback
      *
+     * @link https://image.intervention.io/v3/basics/instantiation#creating-animations
      * @param callable $init
      * @return ImageInterface
      */
diff --git a/src/Interfaces/ImageInterface.php b/src/Interfaces/ImageInterface.php
index 581060c4..57e91bbb 100644
--- a/src/Interfaces/ImageInterface.php
+++ b/src/Interfaces/ImageInterface.php
@@ -44,6 +44,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Return width of current image
      *
+     * @link https://image.intervention.io/v3/basics/meta-information#reading-the-pixel-width
      * @throws RuntimeException
      * @return int
      */
@@ -52,6 +53,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Return height of current image
      *
+     * @link https://image.intervention.io/v3/basics/meta-information#reading-the-pixel-height
      * @throws RuntimeException
      * @return int
      */
@@ -60,6 +62,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Return size of current image
      *
+     * @link https://image.intervention.io/v3/basics/meta-information#reading-the-image-size-as-an-object
      * @throws RuntimeException
      * @return SizeInterface
      */
@@ -68,6 +71,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Encode image with given encoder
      *
+     * @link https://image.intervention.io/v3/basics/image-output#encoding-images
      * @param EncoderInterface $encoder
      * @throws RuntimeException
      * @return EncodedImageInterface
@@ -78,6 +82,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      * Save the image to the specified path in the file system. If no path is
      * given, the image will be saved at its original location.
      *
+     * @link https://image.intervention.io/v3/basics/image-output#writing-images-directly
      * @param null|string $path
      * @throws RuntimeException
      * @return ImageInterface
@@ -87,6 +92,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Apply given modifier to current image
      *
+     * @link https://image.intervention.io/v3/modifying/custom-modifiers
      * @param ModifierInterface $modifier
      * @throws RuntimeException
      * @return ImageInterface
@@ -105,6 +111,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Determine if current image is animated
      *
+     * @link https://image.intervention.io/v3/modifying/animations#check-the-current-image-instance-for-animation
      * @return bool
      */
     public function isAnimated(): bool;
@@ -117,6 +124,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      * string values must represent a percentage value between '0%' and '100%'
      * and the respective frame position is only determined approximately.
      *
+     * @link https://image.intervention.io/v3/modifying/animations#removing-animation
      * @param int|string $position
      * @throws RuntimeException
      * @return ImageInterface
@@ -126,6 +134,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Extract animation frames based on given values and discard the rest
      *
+     * @link https://image.intervention.io/v3/modifying/animations#changing-the-animation-frames
      * @param int $offset
      * @param null|int $length
      * @throws RuntimeException
@@ -136,6 +145,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Return loop count of animated image
      *
+     * @link https://image.intervention.io/v3/modifying/animations#reading-the-animation-iteration-count
      * @return int
      */
     public function loops(): int;
@@ -143,6 +153,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Set loop count of animated image
      *
+     * @link https://image.intervention.io/v3/modifying/animations#changing-the-animation-iteration-count
      * @param int $loops
      * @return ImageInterface
      */
@@ -151,6 +162,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Return exif data of current image
      *
+     * @link https://image.intervention.io/v3/basics/meta-information#exif-information
      * @return mixed
      */
     public function exif(?string $query = null): mixed;
@@ -166,6 +178,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Return image resolution/density
      *
+     * @link https://image.intervention.io/v3/basics/meta-information#image-resolution
      * @throws RuntimeException
      * @return ResolutionInterface
      */
@@ -174,6 +187,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Set image resolution
      *
+     * @link https://image.intervention.io/v3/basics/meta-information#image-resolution
      * @param float $x
      * @param float $y
      * @throws RuntimeException
@@ -184,6 +198,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Get the colorspace of the image
      *
+     * @link https://image.intervention.io/v3/basics/colors#reading-the-colorspace
      * @throws RuntimeException
      * @return ColorspaceInterface
      */
@@ -192,6 +207,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Transform image to given colorspace
      *
+     * @link https://image.intervention.io/v3/basics/colors#changing-the-colorspace
      * @param string|ColorspaceInterface $colorspace
      * @throws RuntimeException
      * @return ImageInterface
@@ -201,6 +217,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Return color of pixel at given position on given frame position
      *
+     * @link https://image.intervention.io/v3/basics/colors#color-information
      * @param int $x
      * @param int $y
      * @param int $frame_key
@@ -212,6 +229,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Return all colors of pixel at given position for all frames of image
      *
+     * @link https://image.intervention.io/v3/basics/colors#color-information
      * @param int $x
      * @param int $y
      * @throws RuntimeException
@@ -223,6 +241,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      * Return color that is mixed with transparent areas when converting to a format which
      * does not support transparency.
      *
+     * @link https://image.intervention.io/v3/basics/colors#transparency
      * @return ColorInterface
      */
     public function blendingColor(): ColorInterface;
@@ -231,6 +250,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      * Set blending color will have no effect unless image is converted into a format
      * which does not support transparency.
      *
+     * @link https://image.intervention.io/v3/basics/colors#transparency
      * @param mixed $color
      * @throws RuntimeException
      * @return ImageInterface
@@ -249,6 +269,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Retrieve ICC color profile of image
      *
+     * @link https://image.intervention.io/v3/basics/colors#color-profiles
      * @throws RuntimeException
      * @return ProfileInterface
      */
@@ -257,6 +278,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Set given icc color profile to image
      *
+     * @link https://image.intervention.io/v3/basics/colors#color-profiles
      * @param ProfileInterface $profile
      * @throws RuntimeException
      * @return ImageInterface
@@ -266,6 +288,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Remove ICC color profile from the current image
      *
+     * @link https://image.intervention.io/v3/basics/colors#color-profiles
      * @throws RuntimeException
      * @return ImageInterface
      */
@@ -274,6 +297,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Apply color quantization to the current image
      *
+     * @link https://image.intervention.io/v3/modifying/effects#reduce-colors
      * @param int $limit
      * @param mixed $background
      * @throws RuntimeException
@@ -284,6 +308,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Sharpen the current image with given strength
      *
+     * @link https://image.intervention.io/v3/modifying/effects#sharpening-effect
      * @param int $amount
      * @throws RuntimeException
      * @return ImageInterface
@@ -293,6 +318,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Turn image into a greyscale version
      *
+     * @link https://image.intervention.io/v3/modifying/effects#convert-image-to-a-greyscale-version
      * @throws RuntimeException
      * @return ImageInterface
      */
@@ -310,6 +336,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Adjust color contrast of the current image
      *
+     * @link https://image.intervention.io/v3/modifying/effects#changing-the-brightness
      * @param int $level
      * @throws RuntimeException
      * @return ImageInterface
@@ -319,6 +346,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Apply gamma correction on the current image
      *
+     * @link https://image.intervention.io/v3/modifying/effects#gamma-correction
      * @param float $gamma
      * @throws RuntimeException
      * @return ImageInterface
@@ -328,6 +356,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Adjust the intensity of the RGB color channels
      *
+     * @link https://image.intervention.io/v3/modifying/effects#color-correction
      * @param int $red
      * @param int $green
      * @param int $blue
@@ -339,6 +368,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Mirror the current image horizontally
      *
+     * @link https://image.intervention.io/v3/modifying/effects#mirror-image-vertically
      * @throws RuntimeException
      * @return ImageInterface
      */
@@ -347,6 +377,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Mirror the current image vertically
      *
+     * @link https://image.intervention.io/v3/modifying/effects#mirror-image-horizontally
      * @throws RuntimeException
      * @return ImageInterface
      */
@@ -355,6 +386,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Blur current image by given strength
      *
+     * @link https://image.intervention.io/v3/modifying/effects#blur-effect
      * @param int $amount
      * @throws RuntimeException
      * @return ImageInterface
@@ -364,6 +396,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Invert the colors of the current image
      *
+     * @link https://image.intervention.io/v3/modifying/effects#invert-colors
      * @throws RuntimeException
      * @return ImageInterface
      */
@@ -372,6 +405,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Apply pixelation filter effect on current image
      *
+     * @link https://image.intervention.io/v3/modifying/effects#pixelation-effect
      * @param int $size
      * @throws RuntimeException
      * @return ImageInterface
@@ -381,6 +415,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Rotate current image by given angle
      *
+     * @link https://image.intervention.io/v3/modifying/effects#image-rotation
      * @param float $angle
      * @param string $background
      * @throws RuntimeException
@@ -391,6 +426,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Draw text on image
      *
+     * @ink https://image.intervention.io/v3/modifying/text-fonts
      * @param string $text
      * @param int $x
      * @param int $y
@@ -403,6 +439,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Resize image to the given width and/or height
      *
+     * @link https://image.intervention.io/v3/modifying/resizing#simple-image-resizing
      * @param null|int $width
      * @param null|int $height
      * @throws RuntimeException
@@ -413,6 +450,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Resize image to the given width and/or height without exceeding the original dimensions
      *
+     * @link https://image.intervention.io/v3/modifying/resizing#resizing-without-exceeding-the-original-size
      * @param null|int $width
      * @param null|int $height
      * @throws RuntimeException
@@ -423,6 +461,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Resize image to the given width and/or height and keep the original aspect ratio
      *
+     * @link https://image.intervention.io/v3/modifying/resizing#scaling-images
      * @param null|int $width
      * @param null|int $height
      * @throws RuntimeException
@@ -434,6 +473,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      * Resize image to the given width and/or height, keep the original aspect ratio
      * and do not exceed the original image width or height
      *
+     * @link https://image.intervention.io/v3/modifying/resizing#scaling-images-but-do-not-exceed-the-original-size
      * @param null|int $width
      * @param null|int $height
      * @throws RuntimeException
@@ -446,6 +486,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      * the original size. Then this size is positioned on the original and cut out
      * before being resized to the desired size from the arguments
      *
+     * @link https://image.intervention.io/v3/modifying/resizing#fitted-image-resizing
      * @param int $width
      * @param int $height
      * @param string $position
@@ -457,6 +498,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Same as cover() but do not exceed the original image size
      *
+     * @link https://image.intervention.io/v3/modifying/resizing#fitted-resizing-without-exceeding-the-original-size
      * @param int $width
      * @param int $height
      * @param string $position
@@ -471,6 +513,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      * is fixed. A background color can be passed to define the color of the
      * new emerging areas.
      *
+     * @link https://image.intervention.io/v3/modifying/resizing#resize-image-canvas
      * @param null|int $width
      * @param null|int $height
      * @param string $position
@@ -490,6 +533,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      * for the width and height, which will be added or subtracted to the
      * original image size.
      *
+     * @link https://image.intervention.io/v3/modifying/resizing#resize-image-boundaries-relative-to-the-original
      * @param null|int $width
      * @param null|int $height
      * @param string $position
@@ -513,6 +557,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      * but possibly new empty areas on the sides of the result image. These are
      * filled with the specified background color.
      *
+     * @link https://image.intervention.io/v3/modifying/resizing#padded-image-resizing
      * @param int $width
      * @param int $height
      * @param string $background
@@ -531,6 +576,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      * This method does the same as pad(), but the original image is also scaled
      * up if the target size exceeds the original size.
      *
+     * @link https://image.intervention.io/v3/modifying/resizing#padded-resizing-with-upscaling
      * @param int $width
      * @param int $height
      * @param string $background
@@ -550,6 +596,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      * height at a given position. Define optional x,y offset coordinates
      * to move the cutout by the given amount of pixels.
      *
+     * @link https://image.intervention.io/v3/modifying/resizing#crop-image
      * @param int $width
      * @param int $height
      * @param int $offset_x
@@ -571,6 +618,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Place another image into the current image instance
      *
+     * @link https://image.intervention.io/v3/modifying/inserting
      * @param mixed $element
      * @param string $position
      * @param int $offset_x
@@ -597,6 +645,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      *
      * If no coordinates are specified, the entire image area is filled.
      *
+     * @link https://image.intervention.io/v3/modifying/drawing#fill-images-with-color
      * @param mixed $color
      * @param null|int $x
      * @param null|int $y
@@ -608,6 +657,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Draw a single pixel at given position defined by the coordinates x and y in a given color.
      *
+     * @link https://image.intervention.io/v3/modifying/drawing#drawing-a-pixel
      * @param int $x
      * @param int $y
      * @param mixed $color
@@ -619,6 +669,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Draw a rectangle on the current image
      *
+     * @link https://image.intervention.io/v3/modifying/drawing#drawing-a-rectangle
      * @param int $x
      * @param int $y
      * @param callable $init
@@ -630,6 +681,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Draw ellipse on the current image
      *
+     * @link https://image.intervention.io/v3/modifying/drawing#drawing-ellipses
      * @param int $x
      * @param int $y
      * @param callable $init
@@ -641,6 +693,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Draw circle on the current image
      *
+     * @link https://image.intervention.io/v3/modifying/drawing#drawing-a-circle
      * @param int $x
      * @param int $y
      * @param callable $init
@@ -652,6 +705,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Draw a polygon on the current image
      *
+     * @link https://image.intervention.io/v3/modifying/drawing#drawing-a-polygon
      * @param callable $init
      * @throws RuntimeException
      * @return ImageInterface
@@ -661,6 +715,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Draw a line on the current image
      *
+     * @link https://image.intervention.io/v3/modifying/drawing#drawing-a-line
      * @param callable $init
      * @throws RuntimeException
      * @return ImageInterface
@@ -671,6 +726,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      * Encode image to given media (mime) type. If no type is given the image
      * will be encoded to the format of the originally read image.
      *
+     * @link https://image.intervention.io/v3/basics/image-output#encode-images-by-media-mime-type
      * @param null|string $type
      * @throws RuntimeException
      * @return EncodedImageInterface
@@ -682,6 +738,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      * extension is given the image will be encoded to the format of the
      * originally read image.
      *
+     * @link https://image.intervention.io/v3/basics/image-output#encode-images-by-file-extension
      * @param null|string $extension
      * @throws RuntimeException
      * @return EncodedImageInterface
@@ -693,6 +750,7 @@ interface ImageInterface extends IteratorAggregate, Countable
      * the given file path extension is given the image will be encoded to
      * the format of the originally read image.
      *
+     * @link https://image.intervention.io/v3/basics/image-output#encode-images-by-file-path
      * @param null|string $path
      * @throws RuntimeException
      * @return EncodedImageInterface
@@ -702,6 +760,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Encode image to JPEG format
      *
+     * @link https://image.intervention.io/v3/basics/image-output#encoding-jpeg-format
      * @param mixed $options
      * @throws RuntimeException
      * @return EncodedImageInterface
@@ -712,6 +771,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Encode image to Jpeg2000 format
      *
+     * @link https://image.intervention.io/v3/basics/image-output#encoding-jpeg-2000-format
      * @param mixed $options
      * @throws RuntimeException
      * @return EncodedImageInterface
@@ -721,6 +781,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Encode image to Webp format
      *
+     * @link https://image.intervention.io/v3/basics/image-output#encoding-webp-format
      * @param mixed $options
      * @throws RuntimeException
      * @return EncodedImageInterface
@@ -730,6 +791,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Encode image to PNG format
      *
+     * @link https://image.intervention.io/v3/basics/image-output#encoding-png-format
      * @param mixed $options
      * @throws RuntimeException
      * @return EncodedImageInterface
@@ -739,6 +801,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Encode image to GIF format
      *
+     * @link https://image.intervention.io/v3/basics/image-output#encoding-gif-format
      * @param mixed $options
      * @throws RuntimeException
      * @return EncodedImageInterface
@@ -748,6 +811,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Encode image to Bitmap format
      *
+     * @link https://image.intervention.io/v3/basics/image-output#encoding-windows-bitmap-format
      * @param mixed $options
      * @throws RuntimeException
      * @return EncodedImageInterface
@@ -757,6 +821,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Encode image to AVIF format
      *
+     * @link https://image.intervention.io/v3/basics/image-output#encoding-av1-image-file-format-avif
      * @param mixed $options
      * @throws RuntimeException
      * @return EncodedImageInterface
@@ -766,6 +831,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Encode image to TIFF format
      *
+     * @link https://image.intervention.io/v3/basics/image-output#encoding-tiff-format
      * @param mixed $options
      * @throws RuntimeException
      * @return EncodedImageInterface
@@ -775,6 +841,7 @@ interface ImageInterface extends IteratorAggregate, Countable
     /**
      * Encode image to HEIC format
      *
+     * @link https://image.intervention.io/v3/basics/image-output#encoding-heic-format
      * @param mixed $options
      * @throws RuntimeException
      * @return EncodedImageInterface