afh.h

diff --git a/afh.h b/afh.h
index ba72d80e5917b103e879ce221526d1a1a5e3fccc..1ce7fb21994ce4a9b67bdccccae9451f238a7127 100644 (file)
--- a/afh.h
+++ b/afh.h
@@ -1,12 +1,32 @@
 /* Copyright (C) 2005 Andre Noll <maan@tuebingen.mpg.de>, see file COPYING. */
 
-/** \file afh.h Structures for audio format handling (para_server). */
+/** \file afh.h Audio format handlers
+ *
+ * The mission of an audio format handler is to tell whether a given file
+ * is an audio file of a certain type. The core of the API is the \ref
+ * audio_format_handler structure whose methods are called when an audio
+ * file is added to the database of para_server(1). Also the virtual
+ * streaming system calls the functions here to stream a file.
+ *
+ * More precisely, each time a file is added, the \ref
+ * audio_format_handler::get_file_info() method is called to initialize an \ref
+ * afh_info structure which contains all information needed for streaming,
+ * including the metadata tags. A serialized version of this structure is
+ * stored in the audio file table and referenced when the file is streamed.
+ *
+ * Each audio format handler is implemented in a dedicated .c file. For
+ * example, the audio format handler for the mp3 format is \ref mp3_afh.c. All
+ * helper functions decribed here are implemented in \ref afh_common.c, which
+ * also defines the array of audio format handlers known to para_server(1),
+ * para_afh(1) and para_recv(1).
+ */
 
 /**
  * The tags used by all audio format handlers.
  *
- * Paraslash only uses the more common tags. These are recognized
- * for all supported audio formats.
+ * Paraslash only cares about the five metadata tags described in this
+ * structure. Each audio format handler is capable of reading and modifying
+ * these tags.
  */
 struct taginfo {
        /** TPE1 (id3v2) / ARTIST (vorbis) / ART (aac)/ author(spx) */
@@ -29,7 +49,7 @@ struct afh_info {
        uint32_t seconds_total;
        /** Audio handler specific info about the file. */
        char *techinfo;
-       /** Id3 tags, vorbis comments, aac tags. */
+       /** Id3 tags, vorbis comments, aac tags, etc. */
        struct taginfo tags;
        /**
         * The table that specifies the offset of the individual pieces in
@@ -88,8 +108,6 @@ struct audio_format_handler {
         * this audio format handler is unable to decode the given file. On
         * success, the function must return a positive value and fill in the
         * given struct afh_info.
-        *
-        * \sa struct \ref afh_info.
         */
        int (*get_file_info)(char *map, size_t numbytes, int fd,
                struct afh_info *afhi);