ext/RMagick/rmutil.c in rmagick-2.12.2 vs ext/RMagick/rmutil.c in rmagick-2.13.1

- old
+ new

@@ -1,31 +1,39 @@ -/* $Id: rmutil.c,v 1.180 2009/09/26 22:28:59 rmagick Exp $ */ -/*============================================================================\ -| Copyright (C) 2009 by Timothy P. Hunter -| Name: rmutil.c -| Author: Tim Hunter -| Purpose: Utility functions for RMagick -\============================================================================*/ +/**************************************************************************//** + * Utility functions for RMagick. + * + * Copyright &copy; 2002 - 2009 by Timothy P. Hunter + * + * Changes since Nov. 2009 copyright &copy; by Benjamin Thomas and Omer Bar-or + * + * @file rmutil.c + * @version $Id: rmutil.c,v 1.182 2009/12/21 10:34:58 baror Exp $ + * @author Tim Hunter + ******************************************************************************/ #include "rmagick.h" #include <errno.h> static void handle_exception(ExceptionInfo *, Image *, ErrorRetention); -/* - Extern: magick_safe_malloc, magick_malloc, magick_free, magick_realloc - Purpose: ImageMagick versions of standard memory routines. - Notes: use when managing memory that ImageMagick may have - allocated or may free. - - If malloc fails, it raises an exception. - - magick_safe_malloc and magick_safe_realloc prevent exceptions - caused by integer overflow. Added in 6.3.5-9 but backwards - compatible with prior releases. -*/ +/** + * ImageMagick safe version of malloc. + * + * No Ruby usage (internal function) + * + * Notes: + * - Use when managing memory that ImageMagick may have allocated or may free. + * - If malloc fails, it raises an exception. + * - magick_safe_malloc and magick_safe_realloc prevent exceptions caused by + * integer overflow. Added in 6.3.5-9 but backwards compatible with prior + * releases. + * + * @param count the number of quantum elements to allocate + * @param quantum the number of bytes in each quantum + * @return a pointer to a block of memory that is at least count*quantum + */ void * magick_safe_malloc(const size_t count, const size_t quantum) { void *ptr; @@ -36,10 +44,18 @@ } return ptr; } +/** + * ImageMagick version of malloc. + * + * No Ruby usage (internal function) + * + * @param size the size of memory to allocate + * @return pointer to a block of memory + */ void * magick_malloc(const size_t size) { void *ptr; ptr = AcquireMagickMemory(size); @@ -50,17 +66,41 @@ return ptr; } +/** + * ImageMagick version of free. + * + * No Ruby usage (internal function) + * + * @param ptr pointer to the existing block of memory + */ void magick_free(void *ptr) { (void) RelinquishMagickMemory(ptr); } +/** + * ImageMagick safe version of realloc. + * + * No Ruby usage (internal function) + * + * Notes: + * - Use when managing memory that ImageMagick may have allocated or may free. + * - If malloc fails, it raises an exception. + * - magick_safe_malloc and magick_safe_realloc prevent exceptions caused by + * integer overflow. Added in 6.3.5-9 but backwards compatible with prior + * releases. + * + * @param memory the existing block of memory + * @param count the number of quantum elements to allocate + * @param quantum the number of bytes in each quantum + * @return a pointer to a block of memory that is at least count*quantum in size + */ void * magick_safe_realloc(void *memory, const size_t count, const size_t quantum) { void *v; v = ResizeQuantumMemory(memory, count, quantum); @@ -70,10 +110,19 @@ } return v; } +/** + * ImageMagick version of realloc. + * + * No Ruby usage (internal function) + * + * @param ptr pointer to the existing block of memory + * @param size the new size of memory to allocate + * @return pointer to a block of memory + */ void * magick_realloc(void *ptr, const size_t size) { void *v; v = ResizeMagickMemory(ptr, size); @@ -83,30 +132,38 @@ } return v; } -/* - Extern: magick_clone_string - Purpose: make a copy of a string in malloc'd memory - Notes: Any existing string pointed to by *new_str is freed. - CloneString asserts if no memory. No need to check - its return value. - -*/ +/** + * Make a copy of a string in malloc'd memory. + * + * No Ruby usage (internal function) + * + * Notes: + * - Any existing string pointed to by *new_str is freed. + * - CloneString asserts if no memory. No need to check its return value. + * + * @param new_str pointer to the new string + * @param str the string to copy + */ void magick_clone_string(char **new_str, const char *str) { (void) CloneString(new_str, str); } -/* - * Extern: rm_strcasecmp(s1, s2) - * Purpose: compare s1 and s2 ignoring case - * Returns: same as strcmp(3) -*/ +/** + * Compare s1 and s2 ignoring case. + * + * No Ruby usage (internal function) + * + * @param s1 the first string + * @param s2 the second string + * @return same as strcmp(3) + */ int rm_strcasecmp(const char *s1, const char *s2) { while (*s1 && *s2) { @@ -119,15 +176,20 @@ } return (int)(*s1 - *s2); } -/* - * Extern: rm_strncasecmp(s1, s2, n) - * Purpose: compare s1 and s2 ignoring case - * Returns: same as strcmp(3) -*/ +/** + * Compare s1 and s2 ignoring case. + * + * No Ruby usage (internal function) + * + * @param s1 the first string + * @param s2 the second string + * @param n number of characters to compare + * @return same as strcmp(3) + */ int rm_strncasecmp(const char *s1, const char *s2, size_t n) { if (n == 0) { @@ -144,14 +206,19 @@ } return (int)(*s1 - *s2); } -/* - * Extern: rm_check_ary_len(ary, len) - * Purpose: raise exception if array too short -*/ +/** + * Raise exception if array too short. + * + * No Ruby usage (internal function) + * + * @param ary the array + * @param len the minimum length + * @throw IndexError + */ void rm_check_ary_len(VALUE ary, long len) { if (RARRAY_LEN(ary) < len) { @@ -159,14 +226,19 @@ len, (long)RARRAY_LEN(ary)); } } -/* - Extern: rm_check_destroyed - Purpose: raise an error if the image has been destroyed -*/ +/** + * Raise an error if the image has been destroyed. + * + * No Ruby usage (internal function) + * + * @param obj the image + * @return the C image structure for the image + * @throw DestroyedImageError + */ Image * rm_check_destroyed(VALUE obj) { Image *image; @@ -178,39 +250,52 @@ return image; } -/* - Extern: rm_check_frozen - Purpose: raise an error if the image has been destroyed or is frozen -*/ +/** + * Raise an error if the image has been destroyed or is frozen. + * + * No Ruby usage (internal function) + * + * @param obj the image + * @return the C image structure for the image + */ Image * rm_check_frozen(VALUE obj) { Image *image = rm_check_destroyed(obj); rb_check_frozen(obj); return image; } -/* - Extern: rm_no_freeze(obj) - Purpose: overrides freeze in classes that can't be frozen. -*/ +/** + * Overrides freeze in classes that can't be frozen. + * + * No Ruby usage (internal function) + * + * @param obj the object of the class to override + * @return 0 + * @throw TypeError + */ VALUE rm_no_freeze(VALUE obj) { rb_raise(rb_eTypeError, "can't freeze %s", rb_class2name(CLASS_OF(obj))); return (VALUE)0; } -/* - Extern: rm_to_s - Purpose: return obj.to_s, or obj if obj is already a string. -*/ +/** + * Return obj.to_s, or obj if obj is already a string. + * + * No Ruby usage (internal function) + * + * @param obj a Ruby object + * @return a String representation of obj + */ VALUE rm_to_s(VALUE obj) { if (TYPE(obj) != T_STRING) @@ -219,14 +304,19 @@ } return obj; } -/* - Extern: rm_str2cstr(str, &len); - Purpose: Supply our own version of the "obsolete" rb_str2cstr. -*/ +/** + * Supply our own version of the "obsolete" rb_str2cstr. + * + * No Ruby usage (internal function) + * + * @param str the Ruby string + * @param len pointer to a long in which to store the number of characters + * @return a C string version of str + */ char * rm_str2cstr(VALUE str, long *len) { StringValue(str); if (len) @@ -235,47 +325,59 @@ } return RSTRING_PTR(str); } -/* - * Static: arg_is_number - * Purpose: Try to convert the argument to a double, - * raise an exception if fail. -*/ +/** + * Try to convert the argument to a double, raise an exception if fail. + * + * No Ruby usage (internal function) + * + * @param arg the argument + * @return arg + */ static VALUE arg_is_number(VALUE arg) { double d; d = NUM2DBL(arg); d = d; // satisfy icc return arg; } -/* - * Static: rescue_not_str - * Purpose: called when `rb_str_to_str' raised an exception below -*/ +/** + * Called when `rb_str_to_str' raises an exception. + * + * No Ruby usage (internal function) + * + * @param arg the argument + * @return 0 + * @throw TypeError + */ static VALUE rescue_not_str(VALUE arg) { rb_raise(rb_eTypeError, "argument must be a number or a string in the form 'NN%%' (%s given)", rb_class2name(CLASS_OF(arg))); return (VALUE)0; } -/* - * Extern: rm_percentage(obj) - * Purpose: Return a double between 0.0 and 1.0, inclusive. - * If the argument is a number convert to a Float object, - * otherwise it's supposed to be a string in the form "NN%". - * Convert to a number and then to a Float. -*/ +/** + * Return a double between 0.0 and max (the second argument), inclusive. If the + * argument is a number convert to a Float object, otherwise it's supposed to be + * a string in the form * "NN%". Convert to a number and then to a Float. + * + * No Ruby usage (internal function) + * + * @param arg the argument + * @param max the maximum allowed value + * @return a double + */ double -rm_percentage(VALUE arg) +rm_percentage(VALUE arg, double max) { double pct; long pct_long; char *pct_str, *end; int not_num; @@ -298,11 +400,11 @@ rb_raise(rb_eArgError, "expected percentage, got `%s'", pct_str); } if (*end == '%' && pct_long != 0) { - pct = ((double)pct_long) / 100.0; + pct = (((double)pct_long) / 100.0) * max; } else { pct = (double) pct_long; } @@ -322,50 +424,65 @@ return pct; } -/* - Static: check_num2dbl - Purpose: return 0 if rb_num2dbl doesn't raise an exception +/** + * Return 0 if rb_num2dbl doesn't raise an exception. + * + * No Ruby usage (internal function) + * + * @param obj the object to convert to a double + * @return 0 */ static VALUE check_num2dbl(VALUE obj) { (void) rb_num2dbl(obj); return INT2FIX(1); } -/* - Static: rescue_not_dbl - Purpose: called if rb_num2dbl raises an exception +/** + * Called if rb_num2dbl raises an exception. + * + * No Ruby usage (internal function) + * + * @param ignored a Ruby object (unused) + * @return 0 */ static VALUE rescue_not_dbl(VALUE ignored) { ignored = ignored; // defeat gcc message return INT2FIX(0); } -/* - Extern: rm_check_num2dbl - Purpose: Return 1 if the object can be converted to a double, 0 otherwise. -*/ +/** + * Return 1 if the object can be converted to a double, 0 otherwise. + * + * No Ruby usage (internal function) + * + * @param obj the object + * @return 1 or 0 + */ int rm_check_num2dbl(VALUE obj) { return FIX2INT(rb_rescue(check_num2dbl, obj, rescue_not_dbl, (VALUE)0)); } -/* - * Extern: rm_str_to_pct - * Purpose: Given a string in the form NN% return the corresponding double. +/** + * Given a string in the form NN% return the corresponding double. * -*/ + * No Ruby usage (internal function) + * + * @param str the string + * @return a double + */ double rm_str_to_pct(VALUE str) { long pct; char *pct_str, *end; @@ -390,17 +507,21 @@ return pct / 100.0; } -/* - * Extern: rm_fuzz_to_dbl(obj) - * Purpose: If the argument is a number, convert it to a double. - * Otherwise it's supposed to be a string in the form 'NN%'. - * Return a percentage of QuantumRange. - * Notes: Called from Image#fuzz= and Info#fuzz= -*/ +/** + * If the argument is a number, convert it to a double. Otherwise it's supposed + * to be a string in the form 'NN%'. Return a percentage of QuantumRange. + * + * No Ruby usage (internal function) + * + * @param fuzz_arg the fuzz argument + * @return a double + * @see Image_fuzz + * @see Image_fuzz_eq + */ double rm_fuzz_to_dbl(VALUE fuzz_arg) { double fuzz; char *fuzz_str, *end; @@ -444,19 +565,25 @@ return fuzz; } -/* - Extern: rm_app2quantum - Purpose: Convert a application-supplied number to a Quantum. If the object - is a Float, truncate it before converting. - Notes: Ruby says that 2147483647.5 doesn't fit into an unsigned long. - If you truncate it, it works. - Should use this only when the input value is possibly subject - to this problem. -*/ +/** + * Convert a application-supplied number to a Quantum. If the object is a Float, + * truncate it before converting. + * + * No Ruby usage (internal function) + * + * Notes: + * - Ruby says that 2147483647.5 doesn't fit into an unsigned long. If you + * truncate it, it works. + * - Should use this only when the input value is possibly subject to this + * problem. + * + * @param obj the application-supplied number + * @return a Quantum + */ Quantum rm_app2quantum(VALUE obj) { volatile VALUE v = obj; @@ -467,32 +594,37 @@ return NUM2QUANTUM(v); } -/* - Extern: rm_cur_image - Purpose: Sends the "cur_image" method to the object. If 'img' - is an ImageList, then cur_image is self[@scene]. - If 'img' is an image, then cur_image is simply - 'self'. - Returns: the return value from "cur_image" -*/ +/** + * Send the "cur_image" method to the object. If 'img' is an ImageList, then + * cur_image is self[\@scene]. If 'img' is an image, then cur_image is simply + * 'self'. + * + * No Ruby usage (internal function) + * + * @param img the object + * @return the return value from "cur_image" + */ VALUE rm_cur_image(VALUE img) { return rb_funcall(img, rm_ID_cur_image, 0); } -/* - Extern: rm_pixelpacket_to_color_name - Purpose: Map the color intensity to a named color - Returns: the named color as a String - Notes: See below for the equivalent function that accepts an Info - structure instead of an Image. -*/ +/** + * Map the color intensity to a named color. + * + * No Ruby usage (internal function) + * + * @param image the image + * @param color the color intensity as a PixelPacket + * @return the named color as a String + * @see rm_pixelpacket_to_color_name_info + */ VALUE rm_pixelpacket_to_color_name(Image *image, PixelPacket *color) { char name[MaxTextExtent]; ExceptionInfo exception; @@ -505,22 +637,27 @@ return rb_str_new2(name); } -/* - Extern: rm_pixelpacket_to_color_name_info - Purpose: Map the color intensity to a named color - Returns: the named color as a String - Notes: Accepts an Info structure instead of an Image (see above). - Simply create an Image from the Info, call QueryColorname, - and then destroy the Image. - If the Info structure is NULL, creates a new one. - - Note that the default depth is always used, and the matte - value is set to False, which means "don't use the alpha channel". -*/ +/** + * Map the color intensity to a named color. + * + * No Ruby usage (internal function) + * + * Notes: + * - Simply create an Image from the Info, call QueryColorname, and then + * destroy the Image. + * - If the Info structure is NULL, creates a new one. + * - The default depth is always used, and the matte value is set to False, + * which means "don't use the alpha channel". + * + * @param info the info + * @param color the color intensity as a PixelPacket + * @return the named color as a String + * @see rm_pixelpacket_to_color_name + */ VALUE rm_pixelpacket_to_color_name_info(Info *info, PixelPacket *color) { Image *image; Info *my_info; @@ -539,17 +676,23 @@ return color_name; } -/* - External: write_temp_image - Purpose: Write a temporary copy of the image to the IM registry - Returns: the "filename" of the registered image - Notes: The `temp_name' argument must point to an char array - of size MaxTextExtent. -*/ +/** + * Write a temporary copy of the image to the IM registry. + * + * No Ruby usage (internal function) + * + * Notes: + * - The `temp_name' argument must point to an char array of size + * MaxTextExtent. + * + * @param image the image + * @param temp_name the temporary name to use + * @return the "filename" of the registered image + */ void rm_write_temp_image(Image *image, char *temp_name) { #define TMPNAM_CLASS_VAR "@@_tmpnam_" @@ -588,16 +731,17 @@ } } -/* - External: delete_temp_image - Purpose: Delete the temporary image from the registry - Returns: void -*/ - +/** + * Delete the temporary image from the registry. + * + * No Ruby usage (internal function) + * + * @param temp_name the name of temporary image in the registry. + */ void rm_delete_temp_image(char *temp_name) { MagickBooleanType okay = DeleteImageRegistry(temp_name+5); @@ -606,33 +750,44 @@ rb_warn("DeleteImageRegistry failed for `%s'", temp_name); } } -/* - External: rm_not_implemented - Purpose: raise NotImplementedError - Notes: Called when a xMagick API is not available. - Replaces Ruby's rb_notimplement function. -*/ +/** + * Raise NotImplementedError. + * + * No Ruby usage (internal function) + * + * Notes: + * - Called when a xMagick API is not available. + * - Replaces Ruby's rb_notimplement function. + * + * @throw NotImpError + */ void rm_not_implemented(void) { rb_raise(rb_eNotImpError, "the `%s' method is not supported by ImageMagick " MagickLibVersionText, rb_id2name(THIS_FUNC())); } -/* - Static: rm_magick_error(msg, loc) - Purpose: create a new ImageMagickError object and raise an exception - Notes: does not return - This funky technique allows me to safely add additional - information to the ImageMagickError object in both 1.6.8 and - 1.8.0. See www.ruby_talk.org/36408. -*/ +/** + * Create a new ImageMagickError object and raise an exception. + * + * No Ruby usage (internal function) + * + * Notes: + * - This funky technique allows me to safely add additional information to + * the ImageMagickError object in both 1.6.8 and 1.8.0. + * + * @param msg the error mesage + * @param loc the location of the error + * @throw ImageMagickError + * @see www.ruby_talk.org/36408. + */ void rm_magick_error(const char *msg, const char *loc) { volatile VALUE exc, mesg, extra; @@ -642,15 +797,26 @@ exc = rb_funcall(Class_ImageMagickError, rm_ID_new, 2, mesg, extra); (void) rb_funcall(rb_cObject, rb_intern("raise"), 1, exc); } -/* - Method: ImageMagickError#initialize(msg, loc) - Purpose: initialize a new ImageMagickError object - store - the "loc" string in the @magick_location instance variable -*/ +/** + * Initialize a new ImageMagickError object - store the "loc" string in the + * \@magick_location instance variable. + * + * Ruby usage: + * - @verbatim ImageMagickError#initialize(msg) @endverbatim + * - @verbatim ImageMagickError#initialize(msg, loc) @endverbatim + * + * Notes: + * - Default loc is nil + * + * @param argc number of input arguments + * @param argv array of input arguments + * @param self this object + * @return self + */ VALUE ImageMagickError_initialize(int argc, VALUE *argv, VALUE self) { VALUE super_argv[1] = {(VALUE)0}; int super_argc = 0; @@ -675,37 +841,52 @@ return self; } -/* - Function: rm_get_property - Purpose: Backport GetImageProperty for pre-6.3.1 versions of ImageMagick -*/ +/** + * Backport GetImageProperty for pre-6.3.1 versions of ImageMagick. + * + * No Ruby usage (internal function) + * + * @param img the image + * @param property the property name + * @return the property value + */ const char * rm_get_property(const Image *img, const char *property) { return GetImageProperty(img, property); } -/* - Function: rm_set_property - Purpose: Backport SetImageProperty for pre-6.3.1 versions of ImageMagick -*/ +/** + * Backport SetImageProperty for pre-6.3.1 versions of ImageMagick. + * + * No Ruby usage (internal function) + * + * @param image the image + * @param property the property name + * @param value the property value + * @return true if successful, otherwise false + */ MagickBooleanType rm_set_property(Image *image, const char *property, const char *value) { return SetImageProperty(image, property, value); } -/* - Function: rm_set_user_artifact - Purpose: If a "user" option is present in the Info, assign its value to - a "user" artifact in each image. -*/ +/** + * If a "user" option is present in the Info, assign its value to a "user" + * artifact in each image. + * + * No Ruby usage (internal function) + * + * @param images a list of images + * @param info the info + */ void rm_set_user_artifact(Image *images, Info *info) { #if defined(HAVE_SETIMAGEARTIFACT) Image *image; const char *value; @@ -725,16 +906,21 @@ info = info; #endif } -/* - Function: rm_get_optional_arguments - Purpose: Collect optional method arguments via Magick::OptionalMethodArguments - Notes: Creates an instance of Magick::OptionalMethodArguments, then yields - to a block in the context of the instance. -*/ +/** + * Collect optional method arguments via Magick::OptionalMethodArguments. + * + * No Ruby usage (internal function) + * + * Notes: + * - Creates an instance of Magick::OptionalMethodArguments, then yields to a + * block in the context of the instance. + * + * @param img the image + */ void rm_get_optional_arguments(VALUE img) { volatile VALUE OptionalMethodArguments; volatile VALUE opt_args; @@ -752,15 +938,19 @@ return; } -/* - Static: copy_options - Purpose: copy image options from the Info structure to the Image structure -*/ #if defined(HAVE_SETIMAGEARTIFACT) +/** + * Copy image options from the Info structure to the Image structure. + * + * No Ruby usage (internal function) + * + * @param image the Image structure to modify + * @param info the Info structure + */ static void copy_options(Image *image, Info *info) { char property[MaxTextExtent]; const char *value, *option; @@ -777,15 +967,19 @@ } } #endif -/* - Extern: rm_sync_image_options - Purpose: Propagate ImageInfo values to the Image - Ref: SyncImageSettings (in mogrify.c) -*/ +/** + * Propagate ImageInfo values to the Image + * + * No Ruby usage (internal function) + * + * @param image the Image structure to modify + * @param info the Info structure + * @see SyncImageSettings in mogrify.c in ImageMagick + */ void rm_sync_image_options(Image *image, Info *info) { MagickStatusType flags; GeometryInfo geometry_info; const char *option; @@ -945,18 +1139,22 @@ copy_options(image, info); #endif } -/* - Function: rm_exif_by_entry - Purpose: replicate old (< 6.3.2) EXIF:* functionality using GetImageProperty - by returning the exif entries as a single string, separated by \n's. - Do this so that RMagick.rb works no matter which version of - ImageMagick is in use. - Notes: see magick/identify.c -*/ +/** + * Replicate old (ImageMagick < 6.3.2) EXIF:* functionality using + * GetImageProperty by returning the exif entries as a single string, separated + * by \n's. Do this so that RMagick.rb works no matter which version of + * ImageMagick is in use. + * + * No Ruby usage (internal function) + * + * @param image the image + * @return string representation of exif properties + * @see magick/identify.c in ImageMagick + */ VALUE rm_exif_by_entry(Image *image) { const char *property, *value; char *str; @@ -1027,18 +1225,22 @@ xfree(str); return v; } -/* - Function: rm_exif_by_number - Purpose: replicate old (< 6.3.2) EXIF:! functionality using GetImageProperty - by returning the exif entries as a single string, separated by \n's. - Do this so that RMagick.rb works no matter which version of - ImageMagick is in use. - Notes: see magick/identify.c -*/ +/** + * Replicate old (ImageMagick < 6.3.2) EXIF:! functionality using + * GetImageProperty by returning the exif entries as a single string, separated + * by \n's. Do this so that RMagick.rb works no matter which version of + * ImageMagick is in use. + * + * No Ruby usage (internal function) + * + * @param image the image + * @return string representation of exif properties + * @see magick/identify.c in ImageMagick + */ VALUE rm_exif_by_number(Image *image) { const char *property, *value; char *str; @@ -1109,15 +1311,25 @@ xfree(str); return v; } -/* - * Extern: rm_get_geometry - * Purpose: Get the values from a Geometry object and return - * them in C variables. -*/ +/** + * Get the values from a Geometry object and return them in C variables. + * + * No Ruby usage (internal function) + * + * Notes: + * - No return value: modifies x, y, width, height, and flag + * + * @param geom the Geometry object + * @param x pointer to the x position of the start of the rectangle + * @param y pointer to the y position of the start of the rectangle + * @param width pointer to the width of the rectangle + * @param height pointer to the height of the rectangle + * @param flag pointer to the Geometry's flag + */ void rm_get_geometry( VALUE geom, long *x, long *y, @@ -1159,15 +1371,21 @@ } } -/* - * Extern: rm_clone_image - * Purpose: clone an image, handle errors - * Notes: don't trace creation - the clone may not be used as an Image - * object. Let the caller do the trace if desired. +/** + * Clone an image, handle errors. + * + * No Ruby usage (internal function) + * + * Notes: + * - Don't trace creation - the clone may not be used as an Image object. Let + * the caller do the trace if desired. + * + * @param image the image to clone + * @return the cloned image */ Image * rm_clone_image(Image *image) { Image *clone; @@ -1184,15 +1402,25 @@ return clone; } -/* - Extern: rm_progress_monitor - Purpose: SetImage(Info)ProgressMonitor exit - Notes: ImageMagick's "tag" argument is unused. We pass along the method name instead. -*/ +/** + * SetImage(Info)ProgressMonitor exit. + * + * No Ruby usage (internal function) + * + * Notes: + * - ImageMagick's "tag" argument is unused. We pass along the method name + * instead. + * + * @param tag ImageMagick argument (unused) + * @param of the offset type + * @param sp the size type + * @param client_data pointer to the progress method to call + * @return true if calling client_data returns a non-nil value, otherwise false + */ MagickBooleanType rm_progress_monitor( const char *tag, const MagickOffsetType of, const MagickSizeType sp, @@ -1217,16 +1445,20 @@ return RTEST(rval) ? MagickTrue : MagickFalse; } -/* - Extern: rm_split - Purpose: Remove the ImageMagick links between images in an scene - sequence. - Notes: The images remain grouped via the ImageList -*/ +/** + * Remove the ImageMagick links between images in an scene sequence. + * + * No Ruby usage (internal function) + * + * Notes: + * - The images remain grouped via the ImageList + * + * @param image the image + */ void rm_split(Image *image) { if (!image) @@ -1238,15 +1470,20 @@ (void) RemoveFirstImageFromList(&image); } } -/* - Extern: rm_check_image_exception - Purpose: If an ExceptionInfo struct in a list of images indicates a warning, - issue a warning message. If an ExceptionInfo struct indicates an - error, raise an exception and optionally destroy the images. +/** + * If an ExceptionInfo struct in a list of images indicates a warning, issue a + * warning message. If an ExceptionInfo struct indicates an error, raise an + * exception and optionally destroy the images. + * + * No Ruby usage (internal function) + * + * @param imglist the list of images + * @param retention retention strategy in case of an error (either RetainOnError + * or DestroyOnError) */ void rm_check_image_exception(Image *imglist, ErrorRetention retention) { ExceptionInfo exception; @@ -1284,13 +1521,19 @@ (void) DestroyExceptionInfo(&exception); } -/* - * Extern: rm_check_exception - * Purpose: Call handle_exception if there is an exception to handle. +/** + * Call handle_exception if there is an exception to handle. + * + * No Ruby usage (internal function) + * + * @param exception information about the exception + * @param imglist the images that caused the exception + * @param retention retention strategy in case of an error (either RetainOnError + * or DestroyOnError) */ void rm_check_exception(ExceptionInfo *exception, Image *imglist, ErrorRetention retention) { if (exception->severity == UndefinedException) @@ -1301,14 +1544,19 @@ handle_exception(exception, imglist, retention); } -/* - * Extern: rm_warning_handler - * Purpose: called from ImageMagick for a warning -*/ +/** + * Called from ImageMagick for a warning. + * + * No Ruby usage (internal function) + * + * @param severity information about the severity of the warning (ignored) + * @param reason the reason for the warning + * @param description description of the warning + */ void rm_warning_handler(const ExceptionType severity, const char *reason, const char *description) { ExceptionType dummy; @@ -1316,14 +1564,19 @@ dummy = severity; dummy = dummy; } -/* - * Extern: rm_error_handler - * Purpose: called from ImageMagick for a error -*/ +/** + * Called from ImageMagick for a error. + * + * No Ruby usage (internal function) + * + * @param severity information about the severity of the error (ignored) + * @param reason the reason for the error + * @param description description of the error + */ void rm_error_handler(const ExceptionType severity, const char *reason, const char *description) { char msg[500]; int len; @@ -1341,29 +1594,40 @@ dummy = severity; dummy = dummy; } -/* - * Extern: rm_fatal_error_handler - * Purpose: called from ImageMagick for a fatal error -*/ +/** + * Called from ImageMagick for a fatal error. + * + * No Ruby usage (internal function) + * + * @param severity information about the severity of the error + * @param reason the reason for the error + * @param description description of the error (ignored) + * @throw FatalImageMagickError + */ void rm_fatal_error_handler(const ExceptionType severity, const char *reason, const char *description) { rb_raise(Class_FatalImageMagickError, GetLocaleExceptionMessage(severity, reason)); description = description; } -/* - * Static: handle_exception - * Purpose: called when rm_check_exception determines that we need - * to either issue a warning message or raise an exception. - * This function allocates a bunch of stack so we don't call - * it unless we have to. -*/ +/** + * Called when rm_check_exception determines that we need to either issue a + * warning message or raise an exception. This function allocates a bunch of + * stack so we don't call it unless we have to. + * + * No Ruby usage (internal function) + * + * @param exception information about the exception + * @param imglist the images that caused the exception + * @param retention retention strategy in case of an error (either RetainOnError + * or DestroyOnError) + */ static void handle_exception(ExceptionInfo *exception, Image *imglist, ErrorRetention retention) { char reason[500]; @@ -1445,12 +1709,16 @@ rm_magick_error(msg, NULL); } -/* - * Extern: rm_ensure_result - * Purpose: RMagick expected a result. If it got NULL instead raise an exception. +/** + * RMagick expected a result. If it got NULL instead raise an exception. + * + * No Ruby usage (internal function) + * + * @param image the expected result + * @throw RuntimeError */ void rm_ensure_result(Image *image) { if (!image)