Improve doc comments for the source/target API (#276)

Author: kleisauke

src/Source.php

@@ -19,9 +19,12 @@ public function __construct(\FFI\CData $pointer)
     }
 
     /**
-     * Make a new source from a file descriptor (a small integer).
-     * Make a new source that is attached to the descriptor. For example:
-     *      $source = VipsSource::newFromDescriptor(0)
+     * Make a new source from a file descriptor. For example:
+     *
+     * ```php
+     * $source = Source::newFromDescriptor(0);
+     * ```
+     *
      * Makes a descriptor attached to stdin.
      * You can pass this source to (for example) @see Image::newFromSource()
      * @throws Exception
@@ -38,9 +41,12 @@ public static function newFromDescriptor(int $descriptor): self
     }
 
     /**
-     * Make a new source from a filename.
-     * Make a new source that is attached to the named file. For example:
-     *      $source = VipsSource::newFromFile("myfile.jpg")
+     * Make a new source from a filename. For example:
+     *
+     * ```php
+     * $source = Source::newFromFile("myfile.jpg");
+     * ```
+     *
      * You can pass this source to (for example) @see Image::newFromSource()
      * @throws Exception
      */
@@ -56,9 +62,12 @@ public static function newFromFile(string $filename): self
     }
 
     /**
-     * Make a new source from a filename.
-     * Make a new source that uses the provided $data. For example:
-     *      $source = VipsSource::newFromFile(file_get_contents("myfile.jpg"))
+     * Make a new source from a memory buffer. For example:
+     *
+     * ```php
+     * $source = Source::newFromMemory(file_get_contents("myfile.jpg"));
+     * ```
+     *
      * You can pass this source to (for example) @see Image::newFromSource()
      * @throws Exception
      */

src/Target.php

@@ -19,9 +19,12 @@ public function __construct(\FFI\CData $pointer)
     }
 
     /**
-     * Make a new target to write to a file descriptor (a small integer).
-     * Make a new target that is attached to the descriptor. For example::
-     *      $target = VipsTarget.newToDescriptor(1)
+     * Make a new target to write to a file descriptor. For example:
+     *
+     * ```php
+     * $target = Target::newToDescriptor(1);
+     * ```
+     *
      * Makes a descriptor attached to stdout.
      * You can pass this target to (for example) @see Image::writeToTarget()
      * @throws Exception
@@ -37,9 +40,12 @@ public static function newToDescriptor(int $descriptor): self
     }
 
     /**
-     * Make a new target to write to a file name.
-     * Make a new target that is attached to the file name. For example::
-     *      $target = VipsTarget.newToFile("myfile.jpg")
+     * Make a new target to write to a filename. For example:
+     *
+     * ```php
+     * $target = Target::newToFile("myfile.jpg");
+     * ```
+     *
      * You can pass this target to (for example) @see Image::writeToTarget()
      * @throws Exception
      */
@@ -55,9 +61,12 @@ public static function newToFile(string $filename): self
     }
 
     /**
-     * Make a new target to write to a memory buffer.
-     * For example::
-     *      $target = VipsTarget.newToMemory()
+     * Make a new target to write to a memory buffer. For example:
+     *
+     * ```php
+     * $target = Target::newToMemory();
+     * ```
+     *
      * You can pass this target to (for example) @see Image::writeToTarget()
      * @throws Exception
      */