API documentation (mostly)
authorTony Cook <tony@develop=help.com>
Mon, 7 Sep 2009 14:06:01 +0000 (14:06 +0000)
committerTony Cook <tony@develop=help.com>
Mon, 7 Sep 2009 14:06:01 +0000 (14:06 +0000)
12 files changed:
Makefile.PL
apidocs.perl
error.c
fills.c
image.c
imdatatypes.h
img16.c
lib/Imager/API.pod
lib/Imager/APIRef.pod
lib/Imager/Files.pod
log.c
tags.c

index 22f9ae9..53966a4 100644 (file)
@@ -232,7 +232,7 @@ imconfig.h : Makefile.PL
        $(PERLRUN) Makefile.PL
        $(ECHO) "==> Your Makefile has been rebuilt - re-run your make command <=="
 '.qq!
-lib/Imager/APIRef.pod : \$(C_FILES) apidocs.perl
+lib/Imager/APIRef.pod : \$(C_FILES) \$(H_FILES) apidocs.perl
        $perl apidocs.perl lib/Imager/APIRef.pod
 
 !.join('', map _im_rule($perl, $_), @ims)
index 7aaa5f6..87c79b3 100644 (file)
@@ -4,7 +4,6 @@ use ExtUtils::Manifest 'maniread';
 
 my $outname = shift || '-';
 
-
 my @funcs = make_func_list();
 my %funcs = map { $_ => 1 } @funcs;
 
@@ -24,6 +23,8 @@ my %funccats;
 my %cats;
 my $synopsis = '';
 my %funcsyns;
+my $order;
+my %order;
 for my $file (@files) {
   open SRC, "< $file"
     or die "Cannot open $file for documentation: $!\n";
@@ -44,9 +45,12 @@ for my $file (@files) {
         if ($synopsis) {
           $funcsyns{$func} = $synopsis;
         }
+       defined $order or $order = 50;
+       $order{$func} = $order;
       }
       undef $func;
       undef $category;
+      undef $order;
       $synopsis = '';
     }
     elsif ($func) {
@@ -56,6 +60,11 @@ for my $file (@files) {
       elsif (/^=synopsis (.*)/) {
         $synopsis .= "$1\n";
       }
+      elsif (/^=order (.*)$/) {
+       $order = $1;
+       $order =~ /^\d+$/
+         or die "=order must specify a number for $func in $file\n";
+      }
       else {
         push @funcdocs, $_;
       }
@@ -79,18 +88,18 @@ you can find the documentation.
 
 =head1 NAME
 
-Imager::APIRef - Imager's C API.
+Imager::APIRef - Imager's C API - reference.
 
 =head1 SYNOPSIS
 
   i_color color;
-  color.rgba.red = 255; color.rgba.green = 0; color.rgba.blue = 255;
+  color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255;
 
 EOS
 
 for my $cat (sort { lc $a cmp lc $b } keys %cats) {
   print OUT "\n  # $cat\n";
-  for my $func (grep $funcsyns{$_}, sort @{$cats{$cat}}) {
+  for my $func (grep $funcsyns{$_}, sort { $order{$a} <=> $order{$b} } @{$cats{$cat}}) {
     my $syn = $funcsyns{$func};
     $syn =~ s/^/  /gm;
     print OUT $syn;
@@ -107,7 +116,11 @@ my %undoc = %funcs;
 
 for my $cat (sort { lc $a cmp lc $b } keys %cats) {
   print OUT "=head2 $cat\n\n=over\n\n";
-  for my $func (sort @{$cats{$cat}}) {
+  my @ordered_funcs = sort {
+    $order{$a} <=> $order{$b}
+      || lc $a cmp lc $b
+    } @{$cats{$cat}};
+  for my $func (@ordered_funcs) {
     print OUT @{$alldocs{$func}}, "\n";
     print OUT "=for comment\nFrom: $from{$func}\n\n";
     delete $undoc{$func};
@@ -118,12 +131,12 @@ for my $cat (sort { lc $a cmp lc $b } keys %cats) {
 # see if we have an uncategorized section
 if (grep $alldocs{$_}, keys %undoc) {
   print OUT "=head2 Uncategorized functions\n\n=over\n\n";
-  for my $func (sort @funcs) {
-    if ($undoc{$func} && $alldocs{$func}) {
-      print OUT @{$alldocs{$func}}, "\n";
-      print OUT "=for comment\nFrom: $from{$func}\n\n";
-      delete $undoc{$func};
-    }
+  #print join(",", grep !exists $order{$_}, @funcs), "\n";
+  for my $func (sort { $order{$a} <=> $order{$b} || $a cmp $b }
+               grep $undoc{$_} && $alldocs{$_}, @funcs) {
+    print OUT @{$alldocs{$func}}, "\n";
+    print OUT "=for comment\nFrom: $from{$func}\n\n";
+    delete $undoc{$func};
   }
   print OUT "\n\n=back\n\n";
 }
@@ -162,7 +175,7 @@ close OUT;
 
 
 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);
+  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);
   open FUNCS, "< imexttypes.h"
     or die "Cannot open imexttypes.h: $!\n";
   my $in_struct;
@@ -186,3 +199,45 @@ sub make_func_list {
     die "Found neither the start nor end of the functions structure\n";
   }
 }
+
+=head1 NAME
+
+apidocs.perl - parse Imager's source for POD documenting the C API
+
+=head1 SYNOPSIS
+
+  perl apidocs.perl lib/Imager/APIRef.pod
+
+=head1 DESCRIPTION
+
+Parses Imager's C sources, including .c, .h and .im files searching
+for function documentation.
+
+Besides the normal POD markup, the following can be included:
+
+=over
+
+=item =category I<category-name>
+
+The category the function should be in.
+
+=item =synopsis I<sample-code>
+
+Sample code using the function to include in the Imager::APIRef SYNOPSIS
+
+=item =order I<integer>
+
+Allows a function to be listed out of order.  If this isn't specified
+it defaults to 50, so a value of 10 will cause the function to be
+listed at the beginning of its category, or 90 to list at the end.
+
+Functions with equal order are otherwise ordered by name.
+
+=back
+
+=head1 AUTHOR
+
+Tony Cook <tonyc@cpan.org>
+
+=cut
+
diff --git a/error.c b/error.c
index 10c3119..a3f172b 100644 (file)
--- a/error.c
+++ b/error.c
@@ -183,7 +183,7 @@ the mark.
 =over
 
 =item i_clear_error()
-
+=synopsis i_clear_error();
 =category Error handling
 
 Clears the error stack.
@@ -209,10 +209,11 @@ void i_clear_error() {
 
 /*
 =item i_push_error(int code, char const *msg)
-
+=synopsis i_push_error(0, "Yep, it's broken");
+=synopsis i_push_error(errno, "Error writing");
 =category Error handling
 
-Called by an imager function to push an error message onto the stack.
+Called by an Imager function to push an error message onto the stack.
 
 No message is pushed if the stack is full (since this means someone
 forgot to call i_clear_error(), or that a function that doesn't do
@@ -253,6 +254,8 @@ void i_push_error(int code, char const *msg) {
 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.
+
 =cut
 */
 void i_push_errorvf(int code, char const *fmt, va_list ap) {
@@ -271,11 +274,13 @@ void i_push_errorvf(int code, char const *fmt, va_list ap) {
 
 /*
 =item i_push_errorf(int code, char const *fmt, ...)
-
+=synopsis i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
 =category Error handling
 
 A version of i_push_error() that does printf() like formating.
 
+Does not support perl specific format codes.
+
 =cut
 */
 void i_push_errorf(int code, char const *fmt, ...) {
diff --git a/fills.c b/fills.c
index ac9660a..9bb2cb1 100644 (file)
--- a/fills.c
+++ b/fills.c
@@ -180,7 +180,7 @@ static i_fill_solid_t base_solid_fill =
 
 /*
 =item i_fill_destroy(fill)
-
+=order 90
 =category Fills
 =synopsis i_fill_destroy(fill);
 
diff --git a/image.c b/image.c
index 5dba629..d1aa208 100644 (file)
--- a/image.c
+++ b/image.c
@@ -480,7 +480,7 @@ i_img_exorcise(i_img *im) {
 
 /* 
 =item i_img_destroy(img)
-
+=order 90
 =category Image creation/destruction
 =synopsis i_img_destroy(img)
 
@@ -537,12 +537,15 @@ i_img_info(i_img *im,int *info) {
 
 /*
 =item i_img_setmask(im, ch_mask)
-
+=category Image Information
 =synopsis // only channel 0 writeable 
 =synopsis i_img_setmask(img, 0x01);
 
 Set the image channel mask for I<im> to I<ch_mask>.
 
+The image channel mask gives some control over which channels can be
+written to in the image.
+
 =cut
 */
 void
@@ -551,8 +554,8 @@ i_img_setmask(i_img *im,int ch_mask) { im->ch_mask=ch_mask; }
 
 /*
 =item i_img_getmask(im)
-
-=synopsis mask = i_img_getmask(img);
+=category Image Information
+=synopsis int mask = i_img_getmask(img);
 
 Get the image channel mask for I<im>.
 
@@ -563,8 +566,8 @@ i_img_getmask(i_img *im) { return im->ch_mask; }
 
 /*
 =item i_img_getchannels(im)
-
-=synopsis channels = i_img_getchannels(img);
+=category Image Information
+=synopsis int channels = i_img_getchannels(img);
 
 Get the number of channels in I<im>.
 
@@ -575,8 +578,8 @@ i_img_getchannels(i_img *im) { return im->channels; }
 
 /*
 =item i_img_get_width(im)
-
-=synopsis width = i_img_get_width(im);
+=category Image Information
+=synopsis i_img_dim width = i_img_get_width(im);
 
 Returns the width in pixels of the image.
 
@@ -589,8 +592,8 @@ i_img_get_width(i_img *im) {
 
 /*
 =item i_img_get_height(im)
-
-=synopsis height = i_img_get_height(im);
+=category Image Information
+=synopsis i_img_dim height = i_img_get_height(im);
 
 Returns the height in pixels of the image.
 
index 21fe65a..007ba10 100644 (file)
@@ -22,6 +22,48 @@ typedef struct { i_sample_t c,m,y,k; } cmyk_color;
 
 typedef int undef_int; /* special value to put in typemaps to retun undef on 0 and 1 on 1 */
 
+/*
+=item i_color
+=category Data Types
+=synopsis i_color black;
+=synopsis black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
+
+Type for 8-bit/sample color.
+
+Samples as per;
+
+  i_color c;
+
+i_color is a union of:
+
+=over
+
+=item *
+
+gray - contains a single element gray_color, eg. c.gray.gray_color
+
+=item *
+
+rgb - contains three elements r, g, b, eg. c.rgb.r
+
+=item *
+
+rgba - contains four elements r, g, b, a, eg. c.rgba.a
+
+=item *
+
+cmyk - contains four elements c, m, y, k, eg. C<c.cmyk.y>.  Note that
+Imager never uses CMYK colors except when reading/writing files.
+
+=item *
+
+channels - an array of four channels, eg C<c.channels[2]>.
+
+=back
+
+=cut
+*/
+
 typedef union {
   gray_color gray;
   rgb_color rgb;
@@ -40,6 +82,17 @@ typedef struct { i_fsample_t r, g, b; } i_frgb_color_t;
 typedef struct { i_fsample_t r, g, b, a; } i_frgba_color_t;
 typedef struct { i_fsample_t c, m, y, k; } i_fcmyk_color_t;
 
+/*
+=item i_fcolor
+=category Data Types
+
+This is the double/sample color type.
+
+Its layout exactly corresponds to i_color.
+
+=cut
+*/
+
 typedef union {
   i_fgray_color_t gray;
   i_frgb_color_t rgb;
@@ -107,12 +160,25 @@ typedef int (*i_f_gsamp_bits_t)(i_img *im, int x, int r, int y, unsigned *samp,
 typedef int (*i_f_psamp_bits_t)(i_img *im, int x, int r, int y, unsigned const *samp,
                                 const int *chans, int chan_count, int bits);
 
+/*
+=item i_img_dim
+=category Data Types
+=synopsis i_img_dim x;
+=order 90
+
+A signed integer type that represents an image dimension or ordinate.
+
+May be larger than int on some platforms.
+
+=cut
+*/
 typedef int i_img_dim;
 
 /*
 =item i_img
 =category Data Types
 =synopsis i_img *img;
+=order 10
 
 This is Imager's image type.
 
@@ -270,10 +336,6 @@ typedef struct {
 
 */
 
-
-
-
-
 /* bitmap mask */
 
 struct i_bitmap {
@@ -287,12 +349,6 @@ int btm_test(struct i_bitmap *btm,int x,int y);
 void btm_set(struct i_bitmap *btm,int x,int y);
 
 
-
-
-
-
-
-
 /* Stack/Linked list */
 
 struct llink {
@@ -421,6 +477,18 @@ typedef enum {
   i_fts_circle
 } i_ft_supersample;
 
+/*
+=item i_fill_t
+=category Data Types
+=synopsis i_fill_t *fill;
+
+This is the "abstract" base type for Imager's fill types.
+
+Unless you're implementing a new fill type you'll typically treat this
+as an opaque type.
+
+=cut
+*/
 
 typedef struct i_fill_tag
 {
diff --git a/img16.c b/img16.c
index 028539d..321821e 100644 (file)
--- a/img16.c
+++ b/img16.c
@@ -145,7 +145,7 @@ typedef unsigned short i_sample16_t;
 /*
 =item i_img_16_new(x, y, ch)
 
-=category Image creation
+=category Image creation/destruction
 =synopsis i_img *img = i_img_16_new(width, height, channels);
 
 Create a new 16-bit/sample image.
index cc8839e..2f16868 100644 (file)
@@ -235,6 +235,16 @@ include Imager 0.48 as a PREREQ_PM:
     Imager => 0.48,
    },
 
+=item *
+
+Since you use Imager::ExtUtils in Makefile.PL (or Build.PL) you should
+include Imager in your configure_requires:
+
+   META_MERGE =>
+   {
+     configure_requires => { Imager => "0.48" }
+   },
+
 =back
 
 =head1 AUTHOR
index 8220a1a..320f064 100644 (file)
@@ -6,64 +6,76 @@ you can find the documentation.
 
 =head1 NAME
 
-Imager::APIRef - Imager's C API.
+Imager::APIRef - Imager's C API - reference.
 
 =head1 SYNOPSIS
 
   i_color color;
-  color.rgba.red = 255; color.rgba.green = 0; color.rgba.blue = 255;
+  color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255;
 
 
   # Data Types
   i_img *img;
+  i_color black;
+  black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
+  i_fill_t *fill;
+  i_img_dim x;
 
   # Drawing
   i_arc(im, 50, 50, 20, 45, 135, &color);
+  i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
   i_arc_aa(im, 50, 50, 35, 90, 135, &color);
   i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill);
-  i_arc_cfill(im, 50, 50, 35, 90, 135, fill);
+  i_circle_aa(im, 50, 50, 45, &color);
   i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color).
-  i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
   i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color);
-  i_circle_aa(im, 50, 50, 45, &color);
-  i_flood_cfill(im, 50, 50, fill);
-  i_flood_cfill_border(im, 50, 50, fill, border);
+  i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill);
   i_flood_fill(im, 50, 50, &color);
+  i_flood_cfill(im, 50, 50, fill);
   i_flood_fill_border(im, 50, 50, &color, &border);
+  i_flood_cfill_border(im, 50, 50, fill, border);
 
   # Error handling
+  i_clear_error();
+  i_push_error(0, "Yep, it's broken");
+  i_push_error(errno, "Error writing");
+  i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
 
   # Files
+  i_set_image_file_limits(500, 500, 1000000);
   i_get_image_file_limits(&width, &height, &bytes)
   i_i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t))
-  i_set_image_file_limits(500, 500, 1000000);
 
   # Fills
-  i_fill_destroy(fill);
-  fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear, 
-                          i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
+  i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
+  i_fill_t *fill = i_new_fill_solid(&color, combine);
   i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy);
   i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy);
   i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine);
-  i_fill_t *fill = i_new_fill_solid(&color, combine);
-  i_fill_t *fill = i_new_fill_solidf(&fcolor, combine);
+  fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear, 
+                          i_fr_triangle, 0, i_fts_grid, 9, 1, segs);
+  i_fill_destroy(fill);
 
   # Image
 
-  # Image creation
-  i_img *img = i_img_16_new(width, height, channels);
-
   # Image creation/destruction
   i_img *img = i_img_8_new(width, height, channels);
-  i_img_destroy(img)
-  i_img *img = i_img_double_new(width, height, channels);
-  i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
   i_img *img = i_sametype(src, width, height);
   i_img *img = i_sametype_chans(src, width, height, channels);
+  i_img *img = i_img_pal_new(width, height, channels, max_palette_size)
+  i_img *img = i_img_double_new(width, height, channels);
+  i_img *img = i_img_16_new(width, height, channels);
+  i_img_destroy(img)
 
   # Image Implementation
 
   # Image Information
+  // only channel 0 writeable 
+  i_img_setmask(img, 0x01);
+  int mask = i_img_getmask(img);
+  int channels = i_img_getchannels(img);
+  i_img_dim width = i_img_get_width(im);
+  i_img_dim height = i_img_get_height(im);
 
   # Image quantization
 
@@ -72,6 +84,9 @@ Imager::APIRef - Imager's C API.
   # Paletted images
 
   # Tags
+  i_tags_set(&img->tags, "i_comment", -1);
+  i_tags_setn(&img->tags, "i_xres", 204);
+  i_tags_setn(&img->tags, "i_yres", 196);
 
 =head1 DESCRIPTION
 
@@ -171,6 +186,76 @@ i_f_psamp_bits - implements i_psamp_bits() for this image.
 =back
 
 
+=for comment
+From: File imdatatypes.h
+
+=item i_color
+
+Type for 8-bit/sample color.
+
+Samples as per;
+
+  i_color c;
+
+i_color is a union of:
+
+=over
+
+=item *
+
+gray - contains a single element gray_color, eg. c.gray.gray_color
+
+=item *
+
+rgb - contains three elements r, g, b, eg. c.rgb.r
+
+=item *
+
+rgba - contains four elements r, g, b, a, eg. c.rgba.a
+
+=item *
+
+cmyk - contains four elements c, m, y, k, eg. C<c.cmyk.y>.  Note that
+Imager never uses CMYK colors except when reading/writing files.
+
+=item *
+
+channels - an array of four channels, eg C<c.channels[2]>.
+
+=back
+
+
+=for comment
+From: File imdatatypes.h
+
+=item i_fcolor
+
+This is the double/sample color type.
+
+Its layout exactly corresponds to i_color.
+
+
+=for comment
+From: File imdatatypes.h
+
+=item i_fill_t
+
+This is the "abstract" base type for Imager's fill types.
+
+Unless you're implementing a new fill type you'll typically treat this
+as an opaque type.
+
+
+=for comment
+From: File imdatatypes.h
+
+=item i_img_dim
+
+A signed integer type that represents an image dimension or ordinate.
+
+May be larger than int on some platforms.
+
+
 =for comment
 From: File imdatatypes.h
 
@@ -505,7 +590,6 @@ From: File imext.c
 
 =item i_clear_error()
 
-
 Clears the error stack.
 
 Called by any imager function before doing any other processing.
@@ -516,8 +600,7 @@ From: File error.c
 
 =item i_push_error(int code, char const *msg)
 
-
-Called by an imager function to push an error message onto the stack.
+Called by an Imager function to push an error message onto the stack.
 
 No message is pushed if the stack is full (since this means someone
 forgot to call i_clear_error(), or that a function that doesn't do
@@ -529,9 +612,10 @@ From: File error.c
 
 =item i_push_errorf(int code, char const *fmt, ...)
 
-
 A version of i_push_error() that does printf() like formating.
 
+Does not support perl specific format codes.
+
 
 =for comment
 From: File error.c
@@ -542,6 +626,8 @@ From: File error.c
 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.
+
 
 =for comment
 From: File error.c
@@ -601,15 +687,6 @@ From: File limits.c
 
 =over
 
-=item i_fill_destroy(fill)
-
-
-Call to destroy any fill object.
-
-
-=for comment
-From: File fills.c
-
 =item i_new_fill_fount(xa, ya, xb, yb, type, repeat, combine, super_sample, ssample_param, count, segs)
 
 
@@ -688,6 +765,14 @@ Create a solid fill based on a float color.
 If combine is non-zero then alpha values will be combined.
 
 
+=for comment
+From: File fills.c
+
+=item i_fill_destroy(fill)
+
+Call to destroy any fill object.
+
+
 =for comment
 From: File fills.c
 
@@ -772,7 +857,7 @@ From: File rubthru.im
 
 =back
 
-=head2 Image creation
+=head2 Image creation/destruction
 
 =over
 
@@ -787,13 +872,6 @@ Returns the image on success, or NULL on failure.
 =for comment
 From: File img16.c
 
-
-=back
-
-=head2 Image creation/destruction
-
-=over
-
 =item i_img_8_new(x, y, ch)
 
 
@@ -802,15 +880,6 @@ Creates a new image object I<x> pixels wide, and I<y> pixels high with
 I<ch> channels.
 
 
-=for comment
-From: File image.c
-
-=item i_img_destroy(img)
-
-
-Destroy an image object
-
-
 =for comment
 From: File image.c
 
@@ -854,6 +923,14 @@ Returns an image of the same type (sample size).
 For paletted images the equivalent direct type is returned.
 
 
+=for comment
+From: File image.c
+
+=item i_img_destroy(img)
+
+Destroy an image object
+
+
 =for comment
 From: File image.c
 
@@ -920,6 +997,38 @@ The number of channels holding color information.
 =for comment
 From: File immacros.h
 
+=item i_img_get_height(im)
+
+Returns the height in pixels of the image.
+
+
+=for comment
+From: File image.c
+
+=item i_img_get_width(im)
+
+Returns the width in pixels of the image.
+
+
+=for comment
+From: File image.c
+
+=item i_img_getchannels(im)
+
+Get the number of channels in I<im>.
+
+
+=for comment
+From: File image.c
+
+=item i_img_getmask(im)
+
+Get the image channel mask for I<im>.
+
+
+=for comment
+From: File image.c
+
 =item i_img_has_alpha(im)
 
 
@@ -929,6 +1038,17 @@ Return true if the image has an alpha channel.
 =for comment
 From: File immacros.h
 
+=item i_img_setmask(im, ch_mask)
+
+Set the image channel mask for I<im> to I<ch_mask>.
+
+The image channel mask gives some control over which channels can be
+written to in the image.
+
+
+=for comment
+From: File image.c
+
 
 =back
 
@@ -985,6 +1105,14 @@ From: File quant.c
 
 =over
 
+=item i_lhead(file, line)
+
+This is an internal function called by the mm_log() macro.
+
+
+=for comment
+From: File log.c
+
 =item i_loog(level, format, ...)
 
 This is an internal function called by the mm_log() macro.
@@ -1255,9 +1383,13 @@ From: File tags.c
 
 =item i_tags_set(tags, name, data, size)
 
-
 Sets the given tag to the string I<data>
 
+If size is -1 then the strlen(I<data>) bytes are stored.
+
+Even on failure, if an existing tag I<name> exists, it will be
+removed.
+
 
 =for comment
 From: File tags.c
@@ -1295,93 +1427,14 @@ From: File tags.c
 
 =item i_tags_setn(tags, name, idata)
 
-
 Sets the given tag to the integer I<idata>
 
-
-=for comment
-From: File tags.c
-
-
-=back
-
-=head2 Uncategorized functions
-
-=over
-
-=item i_img_get_height(im)
-
-
-Returns the height in pixels of the image.
-
-
-=for comment
-From: File image.c
-
-=item i_img_get_width(im)
-
-
-Returns the width in pixels of the image.
-
-
-=for comment
-From: File image.c
-
-=item i_img_getchannels(im)
-
-
-Get the number of channels in I<im>.
-
-
-=for comment
-From: File image.c
-
-=item i_img_getmask(im)
-
-
-Get the image channel mask for I<im>.
+Even on failure, if an existing tag I<name> exists, it will be
+removed.
 
 
 =for comment
-From: File image.c
-
-=item i_img_setmask(im, ch_mask)
-
-
-Set the image channel mask for I<im> to I<ch_mask>.
-
-
-=for comment
-From: File image.c
-
-
-
-=back
-
-
-=head1 UNDOCUMENTED
-
-The following API functions are undocumented so far, hopefully this
-will change:
-
-=over
-
-=item *
-
-B<i_color>
-
-=item *
-
-B<i_fcolor>
-
-=item *
-
-B<i_fill_t>
-
-=item *
-
-B<i_lhead>
-
+From: File tags.c
 
 
 =back
index 546cbcd..b7d612b 100644 (file)
@@ -1252,7 +1252,7 @@ paletted image being returned as a direct color image.  Default: 1
     or die $img->errstr;
 
 This was introduced in Imager 0.60.  Previously reading ICO images
-acted as if C<<ico_masked => 0>>.
+acted as if C<ico_masked =E<gt> 0>.
 
 =back
 
diff --git a/log.c b/log.c
index 2f043a9..a32db1b 100644 (file)
--- a/log.c
+++ b/log.c
@@ -90,6 +90,14 @@ i_loog(int level,const char *fmt, ... ) {
   }
 }
 
+/*
+=item i_lhead(file, line)
+=category Logging
+
+This is an internal function called by the mm_log() macro.
+
+=cut
+*/
 
 void
 i_lhead(const char *file, int line) {
diff --git a/tags.c b/tags.c
index 2579f26..6812a49 100644 (file)
--- a/tags.c
+++ b/tags.c
@@ -83,7 +83,7 @@ void i_tags_new(i_img_tags *tags) {
 
 Adds a tag that has an integer value.  A simple wrapper around i_tags_add().
 
-Duplicate tags can be added.
+Use i_tags_setn() instead, this function may be removed in the future.
 
 Returns non-zero on success.
 
@@ -99,7 +99,7 @@ int i_tags_addn(i_img_tags *tags, char const *name, int code, int idata) {
 
 Adds a tag to the tags list.
 
-Duplicate tags can be added.
+Use i_tags_set() instead, this function may be removed in the future.
 
 Returns non-zero on success.
 
@@ -615,11 +615,16 @@ int i_tags_get_string(i_img_tags *tags, char const *name, int code,
 
 /*
 =item i_tags_set(tags, name, data, size)
-
+=synopsis i_tags_set(&img->tags, "i_comment", -1);
 =category Tags
 
 Sets the given tag to the string I<data>
 
+If size is -1 then the strlen(I<data>) bytes are stored.
+
+Even on failure, if an existing tag I<name> exists, it will be
+removed.
+
 =cut
 */
 
@@ -632,11 +637,15 @@ i_tags_set(i_img_tags *tags, char const *name, char const *data, int size) {
 
 /*
 =item i_tags_setn(tags, name, idata)
-
+=synopsis i_tags_setn(&img->tags, "i_xres", 204);
+=synopsis i_tags_setn(&img->tags, "i_yres", 196);
 =category Tags
 
 Sets the given tag to the integer I<idata>
 
+Even on failure, if an existing tag I<name> exists, it will be
+removed.
+
 =cut
 */