Improvement: Add @throws tags to phpdoc

[chregu]

PHPStorm/IntelliJ can now handle @throws tags from phpdoc much better than before (maybe other IDEs too), but they're all missing in the phpdocs of this package. With the consequence that my IDE complains about "Useless catch" when I catch a Vips/Exception.

Would be great, if those could be added some day (I looked into generate_phpdoc.rb, but couldn't get it running, maybe due to #56 and I also don't know, which methods actually can throw an exception, and which don't).

[jcupitt]

OK, it doesn't look too hard:

https://docs.phpdoc.org/references/phpdoc/tags/throws.html

[jcupitt]

Hello, is it enough just to add a @throws line? For example:

 * @method array find_trim(array $options = []) Search an image for non-edge areas.
 *     Return array with: [
 *         'left' => @type integer Left edge of image.
 *         'top' => @type integer Top edge of extract area.
 *         'width' => @type integer Width of extract area.
 *         'height' => @type integer Height of extract area.
 *     ];
 *     @throws Exception

You need ruby-vips 1.x for gen-doc. Try:

gem install ruby-vips -v 1.0.6

You'll find it'll complain about the Vips::init. Change it to Vips::init("").

[jcupitt]

There's a branch with some decls added and generate_phpdoc.rb updated. It might work!

[jcupitt]

... and there's a reason C++ has deprecated all exception declarations :( I don't think they add any useful information.

[chregu]

Thanks will test. And about the usefulness, once can certainly argue about that, but here, since it's calling the c-extension part, it's not really obvious that those methods throw an exception and not even the best IDE can figure them out by itself. So it actually helps while coding to not miss possible exceptions, IMHO.

[kleisauke]

All looks OK to me, I've fixed the string to int conversion for blend modes and missing @throws declarations in #63.

[chregu]

Looks good to me as well. Any chance we get a new release (1.1.0 I guess would be the next logic thing from a semver perspective) soon? Especially also for the composite method (which has a different way to be called in 1.0.2, since I guess that wasn't available and therefore not supported back then)

Here's what I currently do to make a distinction between the two modes
https://github.com/rokka-io/imagine-vips/blob/master/lib/Imagine/Vips/Image.php#L262

So technically it's a BC break (which would need a 2.0 release for semver reasons), but I'd be fine with a 1.1.0. For my use case it doesn't matter, I just change composer.json to require ^1.1.0 of php-vips and can then remove the old way of calling the composite method.

[jcupitt]

OK, merged to master.

Yes, I plan to update all the bindings now that 8.6 is finally done.

[jcupitt]

Also, thank you for suggesting this useful improvement Christian!