mp3_afh: Document id3_field_init() and id3_field_finish().

These functions are somewhat obscure because they are not part of the
libid3tag API. They are not part of the internal paraslash API either,
so their documentation should not be shown on the API page. Exclude the
documentation with the doxygen \cond and \endcond markers.

diff --git a/mp3_afh.c b/mp3_afh.c
index 56f28a09d8eb9fd18a9ba2262f14a58c6cec7997..1fc3b62dcd18226c3fbe2196e36648e0767afb14 100644 (file)
--- a/mp3_afh.c
+++ b/mp3_afh.c
@@ -175,10 +175,34 @@ static int mp3_get_id3(unsigned char *map, size_t numbytes, __a_unused int fd,
        return ret;
 }
 
-/* These helpers are not mentioned in the libid3tag header file. */
+/*
+ * The two helpers below are called during tag replacement if libid3tag is
+ * present. They are implemented and exported in the library but libid3tag.h
+ * does not declare them, so we declare them here.
+ */
+
+/** \cond libid3tag */
+
+/*
+ * To replace a tag with libid3tag one has to pass frames of id3 fields
+ * to particular functions of the id3tag library. The various field types
+ * specify text encoding, language, string, etc. This function initializes
+ * a field to the default value for the given type. It does not allocate
+ * memory and always succeeds.
+ */
 void id3_field_init(union id3_field *field, enum id3_field_type type);
+
+/*
+ * Reset a field, deallocating memory if necessary.
+ *
+ * This first frees any memory already allocated, then calls id3_field_init()
+ * to initialize the field, re-using the old field type. The field pointer
+ * must not be NULL.
+ */
 void id3_field_finish(union id3_field *field);
 
+/** \endcond libid3tag */
+
 /*
  * Frames of type ID3_FRAME_COMMENT contain three fields of type language,
  * string, and fullstring. The third field contains the actual comment.