start to add docs

Author: jcupitt

.gitignore

@@ -7,6 +7,7 @@ acinclude.m4
 aclocal.m4
 autom4te.cache
 build
+docs
 config.guess
 config.h
 config.h.in

README.md

@@ -58,7 +58,7 @@ I used 7.0.10 and configured with:
 
 ```
 $ ./configure --prefix=/home/john/vips --enable-debug --enable-maintainer-zts \
-	--enable-cgi --enable-cli --with-readline
+	--enable-cgi --enable-cli --with-readline --with-openssl
 ```
 
 ### Regenerate build system
@@ -141,7 +141,7 @@ $ ./try1.php ~/pics/k2.jpg x.tif
 
 See `examples/`.
 
-### links
+### Links
 
 http://php.net/manual/en/internals2.php
 
@@ -151,3 +151,20 @@ https://devzone.zend.com/317/extension-writing-part-ii-parameters-arrays-and-zva
 
 https://devzone.zend.com/446/extension-writing-part-iii-resources/
 
+### Documentation
+
+```
+$ pear channel-discover pear.phpdoc.org
+$ pear install phpdoc/phpDocumentor
+$ phpdoc 
+```
+
+### imagick
+
+```
+$ pecl install imagick
+$ php -a
+Interactive mode enabled
+php > dl('imagick.' . PHP_SHLIB_SUFFIX);
+php > $im = new Imagick();
+```

phpdoc.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpdocumentor>
+
+    <parser>
+        <target>docs</target>
+    </parser>
+
+    <transformer>
+        <target>docs</target>
+    </transformer>
+
+    <files>
+        <file>vips.php</file>
+        <file>vips.c</file>
+    </files>
+
+</phpdocumentor>

vips.c

@@ -1,3 +1,7 @@
+/**
+ * C layer of the php-vips binding.
+ */
+
 /* Uncomment for some logging.
 #define VIPS_DEBUG
  */

vips.php

@@ -1,20 +1,33 @@
 <?php
-
-/* This file tries to make a nice API over the raw `vips_call` thing defined 
- * in C.
+/**
+ * php-vips is a php binding for the vips image processing library.
  */
 
 if (!extension_loaded("vips")) {
 	dl('vips.' . PHP_SHLIB_SUFFIX);
 }
 
+/**
+ * The VImage class represents an image. 
+ */
 class VImage implements ArrayAccess
 {
 	/* The resource for the underlying VipsImage.
 	 */
 	private $image;
 
-	function __construct($image) 
+	/**
+	 * Wrap a VImage around an underlying vips resource. 
+	 *
+	 * Don't call this yourself, users should stick to (for example)
+	 * VImage::new_from_file().
+	 *
+	 * @param resource $image The underlying vips image resource that this
+	 * 	class should wrap.
+	 *
+	 * @return a new VImage.
+	 */
+	public function __construct($image) 
 	{
 		$this->image = $image;
 	}
@@ -130,13 +143,31 @@ private static function wrap($result)
 		return $result;
 	}
 
+	/** 
+	 * Create a new VImage from a file on disc.
+	 *
+	 * @param string $filename The file to open.
+	 * @param array $options Any options to pass on to the load operation.
+	 *
+	 * @return A new VImage.
+	 */
 	public static function new_from_file($filename, $options = []) 
 	{
 		$options = self::unwrap($options);
 		$result = vips_image_new_from_file($filename, $options);
 		return self::wrap($result);
 	}
 
+	/** 
+	 * Create a new VImage from a compressed image held as a string. 
+	 *
+	 * @param string $buffer The formatted image to open.
+	 * @param string $option_string Any text-style options to pass to the
+	 * selected loader. 
+	 * @param array $options Any options to pass on to the load operation.
+	 *
+	 * @return A new VImage.
+	 */
 	public static function new_from_buffer($buffer, 
 		$option_string = "", $options = []) 
 	{
@@ -145,37 +176,93 @@ public static function new_from_buffer($buffer,
 		return self::wrap($result);
 	}
 
+	/** 
+	 * Create a new VImage from a php array. 
+	 *
+	 * 2D arrays become 2D images. 1D arrays become 2D images with height 1. 
+	 *
+	 * @param array $array The array to make the image from. 
+	 * @param double $scale The "scale" metadata item. Useful for integer
+	 * convolution masks.
+	 * @param double $offset The "offset" metadata item. Useful for integer
+	 * convolution masks.
+	 *
+	 * @return A new VImage.
+	 */
 	public static function new_from_array($array, $scale = 1, $offset = 0) 
 	{
 		$result = vips_image_new_from_array($array, $scale, $offset);
 		return self::wrap($result);
 	}
 
+	/** 
+	 * Write an image to a file. 
+	 *
+	 * @param string $filename The file to write the image to.
+	 * @param array $options Any options to pass on to the selected save 
+	 * operation.
+	 *
+	 * @return bool TRUE for success and FALSE for failure.
+	 */
 	public function write_to_file($filename, $options = []) 
 	{
 		$options = self::unwrap($options);
 		$result = vips_image_write_to_file($this->image, $filename, $options);
 		return self::wrap($result);
 	}
 
+	/** 
+	 * Write an image to a formatted string. 
+	 *
+	 * @param string $suffix The file type suffix, eg. ".jpg".
+	 * @param array $options Any options to pass on to the selected save 
+	 * operation.
+	 *
+	 * @return string The formatted image. 
+	 */
 	public function write_to_buffer($suffix, $options = []) 
 	{
 		$options = self::unwrap($options);
 		$result = vips_image_write_to_buffer($this->image, $suffix, $options);
 		return self::wrap($result);
 	}
 
+	/**
+	 * Get any property from the underlying image.
+	 * 
+	 * @param string $name The property name. 
+	 *
+	 * @return mixed
+	 */
 	public function __get($name) 
 	{
 		$result = vips_image_get($this->image, $name);
 		return self::wrap($result);
 	}
 
+	/**
+	 * Set any property on the underlying image.
+	 * 
+	 * @param string $name The property name. 
+	 * @param mixed $value The value to set for this property.
+	 *
+	 * @return void
+	 */
 	public function __set($name, $value) 
 	{
 		vips_image_set($this->image, $name, $value);
 	}
 
+	/**
+	 * Call any vips operation.
+	 *
+	 * @param string $name The operation name. 
+	 * @param VImage $instance The instance this operation is being invoked
+	 * from.
+	 * @param mixed[] $arguments An array of arguments to pass to the operation.
+	 *
+	 * @return mixed The result(s) of the operation. 
+	 */
 	public static function call($name, $instance, $arguments) 
 	{
 		/*
@@ -208,11 +295,17 @@ private function call_enum($other, $base, $op, $options = [])
 		}
 	}
 
+	/**
+	 * Call any vips operation as an instance method.
+	 */
 	public function __call($name, $arguments) 
 	{
 		return self::call($name, $this, $arguments); 
 	}
 
+	/**
+	 * Call any vips operation as a class method.
+	 */
 	public static function __callStatic($name, $arguments) 
 	{
 		return self::call($name, NULL, $arguments); 
@@ -245,6 +338,15 @@ public function offsetUnset($offset)
 	 * speedup.
 	 */
 
+	/**
+	 * Add to this image.
+	 *
+	 * @param int|double|int[]|double[]|VImage $other The thing to add to this
+	 * image.
+	 * @param array $options Any options to pass on to the add operation.
+	 *
+	 * @return VImage A new image.
+	 */
 	public function add($other, $options = [])
 	{
 		if ($other instanceof VImage) {
@@ -263,7 +365,7 @@ public function subtract($other, $options = [])
 		}
 		else {
 			$other = map_numeric($other, function ($value) {
-					return -1 * $value;
+				return -1 * $value;
 			});
 			return self::linear($this, 1, $other, $options);
 		}
@@ -287,7 +389,7 @@ public function divide($other, $options = [])
 		}
 		else {
 			$other = map_numeric($other, function ($value) {
-					return $value ** -1;
+				return $value ** -1;
 			});
 			return self::linear($this, $other, 0, $options);
 		}