most numeric parameters to the XS implementation now throw an exception if supplied...

[imager.git] / tags.c

diff --git a/tags.c b/tags.c
index 1892933f464772deca46546811c3a135148d7dae..1d759e7a4699e93e332d8eaefb1a458494a24013 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.
 
@@ -182,7 +182,7 @@ void i_tags_destroy(i_img_tags *tags) {
 
 =category Tags
 
-Searchs for a tag of the given I<name> starting from index I<start>.
+Searches for a tag of the given I<name> starting from index I<start>.
 
 On success returns true and sets *I<entry>.
 
@@ -209,7 +209,7 @@ int i_tags_find(i_img_tags *tags, char const *name, int start, int *entry) {
 
 =category Tags
 
-Searchs for a tag of the given I<code> starting from index I<start>.
+Searches for a tag of the given I<code> starting from index I<start>.
 
 On success returns true and sets *I<entry>.
 
@@ -409,7 +409,7 @@ int i_tags_set_float2(i_img_tags *tags, char const *name, int code,
 
 Retrieve a tag specified by name or code as an integer.
 
-On success sets the i_color *I<value> to the color and returns true.
+On success sets the int *I<value> to the integer and returns true.
 
 On failure returns false.
 
@@ -580,7 +580,7 @@ On failure returns false.
 value_size must be at least large enough for a string representation
 of an integer.
 
-The copied value is always NUL terminated.
+The copied value is always C<NUL> terminated.
 
 =cut
 */
@@ -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
 */
 
@@ -631,11 +636,15 @@ i_tags_set(i_img_tags *tags, char const *name, char const *data, int size) {
 }
 
 /*
-=item i_tags_setn(tags, name, idata)
-
+=item i_tags_setn(C<tags>, C<name>, C<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>
+Sets the given tag to the integer C<idata>
+
+Even on failure, if an existing tag C<name> exists, it will be
+removed.
 
 =cut
 */