fill out documentation

Changes

@@ -1,5 +1,9 @@
 Imager release history.  Older releases can be found in Changes.old
 
+Threads work
+TODO: fill objects should refer to the contexts
+TODO: finish up doc changes
+
 Imager 0.92 - 14 Aug 2012
 ===========
 

apidocs.perl

@@ -187,7 +187,7 @@ =head1 SEE ALSO
 
 
 sub make_func_list {
-  my @funcs = qw(i_img i_color i_fcolor i_fill_t mm_log i_img_color_channels i_img_has_alpha i_img_dim i_DF i_DFc i_DFp i_DFcp i_psamp_bits i_gsamp_bits i_psamp i_psampf);
+  my @funcs = qw(i_img i_color i_fcolor i_fill_t mm_log mm_log i_img_color_channels i_img_has_alpha i_img_dim i_DF i_DFc i_DFp i_DFcp i_psamp_bits i_gsamp_bits i_psamp i_psampf);
   open FUNCS, "< imexttypes.h"
     or die "Cannot open imexttypes.h: $!\n";
   my $in_struct;

context.c

@@ -42,6 +42,9 @@ im_context_new(void) {
 
 /*
 =item im_context_refinc(ctx, where)
+X<im_context_refinc API>
+=section Context objects
+=synopsis im_context_refinc(aIMCTX, "a description");
 
 Add a new reference to the context.
 
@@ -59,9 +62,13 @@ im_context_refinc(im_context_t ctx, const char *where) {
 }
 
 /*
-=item im_context_refdec(ctx)
+=item im_context_refdec(ctx, where)
+X<im_context_refdec API>
+=section Context objects
+=synopsis im_context_refdec(aIMCTX, "a description");
 
-Release memory used by an Imager context object.
+Remove a reference to the context, releasing it if all references have
+been removed.
 
 =cut
 */

error.c

@@ -178,14 +178,18 @@ the mark.
 
 =over
 
-=item i_clear_error()
+=item im_clear_error(ctx)
+X<im_clear_error API>X<i_clear_error API>
+=synopsis im_clear_error(aIMCTX);
 =synopsis i_clear_error();
 =category Error handling
 
 Clears the error stack.
 
 Called by any Imager function before doing any other processing.
 
+Also callable as C<i_clear_error()>.
+
 =cut
 */
 
@@ -206,9 +210,11 @@ im_clear_error(im_context_t ctx) {
 }
 
 /*
-=item i_push_error(int code, char const *msg)
+=item im_push_error(ctx, code, message)
+X<im_push_error API>X<i_push_error API>
 =synopsis i_push_error(0, "Yep, it's broken");
 =synopsis i_push_error(errno, "Error writing");
+=synopsis im_push_error(aIMCTX, 0, "Something is wrong");
 =category Error handling
 
 Called by an Imager function to push an error message onto the stack.
@@ -252,15 +258,20 @@ i_push_error(int code, char const *msg) {
 #endif
 
 /*
-=item i_push_errorvf(int C<code>, char const *C<fmt>, va_list C<ap>)
-
+=item im_push_errorvf(ctx, code, format, args)
+X<im_push_error_vf API>X<i_push_errorvf API>
+=synopsis va_args args;
+=synopsis va_start(args, lastarg);
+=synopsis im_push_errorvf(ctx, code, format, args);
 =category Error handling
 
 Intended for use by higher level functions, takes a varargs pointer
 and a format to produce the finally pushed error message.
 
 Does not support perl specific format codes.
 
+Also callable as C<i_push_errorvf(code, format, args)>
+
 =cut
 */
 void 
@@ -280,11 +291,6 @@ im_push_errorvf(im_context_t ctx, int code, char const *fmt, va_list ap) {
   im_push_error(ctx, code, buf);
 }
 
-void
-(i_push_errorvf)(int code, char const *fmt, va_list ap) {
-  im_push_errorvf(im_get_context(), code, fmt, ap);
-}
-
 /*
 =item i_push_errorf(int code, char const *fmt, ...)
 =synopsis i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
@@ -304,6 +310,17 @@ i_push_errorf(int code, char const *fmt, ...) {
   va_end(ap);
 }
 
+/*
+=item im_push_errorf(ctx, code, char const *fmt, ...)
+=synopsis im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);
+=category Error handling
+
+A version of im_push_error() that does printf() like formatting.
+
+Does not support perl specific format codes.
+
+=cut
+*/
 void
 im_push_errorf(im_context_t ctx, int code, char const *fmt, ...) {
   va_list ap;

image.c

@@ -44,8 +44,11 @@ im_context_t (*im_get_context)(void) = NULL;
 void i_linker_bug_fake(void) { ceil(1); }
 
 /*
-=item i_img_alloc()
+=item im_img_alloc(aIMCTX)
+X<im_img_alloc API>X<i_img_alloc API>
 =category Image Implementation
+=synopsis i_img *im = im_img_alloc(aIMCTX);
+=synopsis i_img *im = i_img_alloc();
 
 Allocates a new i_img structure.
 
@@ -79,13 +82,15 @@ im_img_alloc(pIMCTX) {
 }
 
 /*
-=item i_img_init(C<img>)
+=item im_img_init(aIMCTX, image)
+X<im_img_init API>X<i_img_init API>
 =category Image Implementation
+=synopsis im_img_init(aIMCTX, im);
+=synopsis i_img_init(im);
 
 Imager internal initialization of images.
 
-Currently this does very little, in the future it may be used to
-support threads, or color profiles.
+See L</im_img_alloc(aIMCTX)> for more information.
 
 =cut
 */

imext.c

@@ -567,7 +567,7 @@ int
 Retrieve the context object for the current thread.
 
 Inside Imager itself this is just a function pointer, which the
-Imager.xs BOOT handler initializes for use within perl.  If you're
+F<Imager.xs> BOOT handler initializes for use within perl.  If you're
 taking the Imager code and embedding it elsewhere you need to
 initialize the C<im_get_context> pointer at some point.
 

img16.c

@@ -150,15 +150,18 @@ typedef unsigned short i_sample16_t;
      ((((i_sample16_t *)(bytes))[offset]+127) / 257)
 
 /*
-=item i_img_16_new(x, y, ch)
-
+=item im_img_16_new(ctx, x, y, ch)
+X<im_img_16_new API>X<i_img_16_new API>
 =category Image creation/destruction
+=synopsis i_img *img = im_img_16_new(aIMCTX, width, height, channels);
 =synopsis i_img *img = i_img_16_new(width, height, channels);
 
 Create a new 16-bit/sample image.
 
 Returns the image on success, or NULL on failure.
 
+Also callable as C<i_img_16_new(x, y, ch)>
+
 =cut
 */
 

img8.c

@@ -82,10 +82,10 @@ static i_img IIM_base_8bit_direct =
   }*/
 
 /*
-=item i_img_8_new(x, y, ch)
-
+=item im_img_8_new(ctx, x, y, ch)
+X<im_img_8_new API>X<i_img_8_new API>
 =category Image creation/destruction
-
+=synopsis i_img *img = im_img_8_new(aIMCTX, width, height, channels);
 =synopsis i_img *img = i_img_8_new(width, height, channels);
 
 Creates a new image object I<x> pixels wide, and I<y> pixels high with
@@ -94,7 +94,6 @@ I<ch> channels.
 =cut
 */
 
-
 i_img *
 im_img_8_new(pIMCTX, i_img_dim x,i_img_dim y,int ch) {
   i_img *im;

imgdouble.c

@@ -92,12 +92,16 @@ static i_img IIM_base_double_direct =
 };
 
 /*
-=item i_img_double_new(i_img_dim x, i_img_dim y, int ch)
+=item im_img_double_new(ctx, x, y, ch)
+X<im_img_double_new API>X<i_img_double_new API>
 =category Image creation/destruction
+=synopsis i_img *img = im_img_double_new(aIMCTX, width, height, channels);
 =synopsis i_img *img = i_img_double_new(width, height, channels);
 
 Creates a new double per sample image.
 
+Also callable as C<i_img_double_new(width, height, channels)>.
+
 =cut
 */
 i_img *

iolayer.c

@@ -154,13 +154,16 @@ static void bufchain_destroy(io_glue *ig);
  */
 
 /*
-=item io_new_bufchain(ctx)
+=item im_io_new_bufchain(ctx)
+X<im_io_new_bufchain API>X<i_io_new_bufchain API>
 =order 10
 =category I/O Layers
 
-returns a new io_glue object that has the 'empty' source and but can
+Returns a new io_glue object that has the 'empty' source and but can
 be written to and read from later (like a pseudo file).
 
+Also callable as C<io_new_bufchain()>.
+
 =cut
 */
 
@@ -195,16 +198,20 @@ im_io_new_bufchain(pIMCTX) {
 }
 
 /*
-=item io_new_buffer(data, length)
+=item im_io_new_buffer(ctx, data, length)
+X<im_io_new_buffer API>X<io_new_buffer API>
 =order 10
 =category I/O Layers
 
 Returns a new io_glue object that has the source defined as reading
 from specified buffer.  Note that the buffer is not copied.
 
+   ctx - an Imager context object
    data - buffer to read from
    length - length of buffer
 
+Also callable as C<io_new_buffer(data, length>.
+
 =cut
 */
 
@@ -234,15 +241,19 @@ im_io_new_buffer(pIMCTX, const char *data, size_t len, i_io_closebufp_t closecb,
 
 
 /*
-=item io_new_fd(fd)
+=item im_io_new_fd(ctx, file)
+X<io_new_fd API>X<im_io_new_fd API>
 =order 10
 =category I/O Layers
 
-returns a new io_glue object that has the source defined as reading
+Returns a new io_glue object that has the source defined as reading
 from specified file descriptor.  Note that the the interface to receiving
 data from the io_glue callbacks hasn't been done yet.
 
-   fd - file descriptor to read/write from
+  ctx - and Imager context object
+  file - file descriptor to read/write from
+
+Also callable as C<io_new_fd(file)>.
 
 =cut
 */
@@ -268,7 +279,8 @@ im_io_new_fd(pIMCTX, int fd) {
 }
 
 /*
-=item io_new_cb(p, read_cb, write_cb, seek_cb, close_cb, destroy_cb)
+=item im_io_new_cb(ctx, p, read_cb, write_cb, seek_cb, close_cb, destroy_cb)
+X<im_io_new_cb API>X<io_new_cb API>
 =category I/O Layers
 =order 10
 
@@ -306,6 +318,9 @@ handlers.
 
 =back
 
+Also callable as C<io_new_cb(p, readcb, writecb, seekcb, closecb,
+destroycb)>.
+
 =cut
 */
 
@@ -339,6 +354,7 @@ im_io_new_cb(pIMCTX, void *p, i_io_readl_t readcb, i_io_writel_t writecb,
 
 /*
 =item io_slurp(ig, c)
+X<io_slurp API>
 =category I/O Layers
 
 Takes the source that the io_glue is bound to and allocates space for
@@ -392,6 +408,7 @@ io_slurp(io_glue *ig, unsigned char **c) {
 
 /*
 =item io_glue_destroy(ig)
+X<io_glue_destroy API>
 =category I/O Layers
 =order 90
 =synopsis io_glue_destroy(ig);