From f13efdc785f972e74299420d051f264cf2da9bb4 Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@systemlinux.org>
Date: Wed, 26 Sep 2007 17:13:55 +0200
Subject: [PATCH 1/1] Move enum ls_sorting_method from afs.h to aft.c and add
 documentation.

---
 afs.h | 27 ---------------------------
 aft.c | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 59 insertions(+), 28 deletions(-)

diff --git a/afs.h b/afs.h
index 97bc0332..6b5afcc4 100644
--- a/afs.h
+++ b/afs.h
@@ -31,33 +31,6 @@ struct table_info {
 	enum afs_table_flags flags;
 };
 
-enum ls_sorting_method {
-	/** -sp (default) */
-	LS_SORT_BY_PATH,
-	/** -ss */
-	LS_SORT_BY_SCORE,
-	/** -sl */
-	LS_SORT_BY_LAST_PLAYED,
-	/** -sn */
-	LS_SORT_BY_NUM_PLAYED,
-	/** -sf */
-	LS_SORT_BY_FREQUENCY,
-	/** -sc */
-	LS_SORT_BY_CHANNELS,
-	/** -si */
-	LS_SORT_BY_IMAGE_ID,
-	/** -sy */
-	LS_SORT_BY_LYRICS_ID,
-	/** -sb */
-	LS_SORT_BY_BITRATE,
-	/** -sd */
-	LS_SORT_BY_DURATION,
-	/** -sa */
-	LS_SORT_BY_AUDIO_FORMAT,
-	/** -sh */
-	LS_SORT_BY_HASH,
-};
-
 enum play_mode {PLAY_MODE_MOOD, PLAY_MODE_PLAYLIST};
 
 struct audio_file_data {
diff --git a/aft.c b/aft.c
index 4ff7ef19..f8e8f40b 100644
--- a/aft.c
+++ b/aft.c
@@ -16,38 +16,96 @@
 #include "string.h"
 #include "vss.h"
 
-#define AFS_AUDIO_FILE_DIR "/home/mp3"
+#define AFS_AUDIO_FILE_DIR "/home/mp3" /* FIXME: Use cwd instead */
 
 static struct osl_table *audio_file_table;
 
+/** The different sorting methods of the ls command. */
+enum ls_sorting_method {
+	/** -sp (default) */
+	LS_SORT_BY_PATH,
+	/** -ss */
+	LS_SORT_BY_SCORE,
+	/** -sl */
+	LS_SORT_BY_LAST_PLAYED,
+	/** -sn */
+	LS_SORT_BY_NUM_PLAYED,
+	/** -sf */
+	LS_SORT_BY_FREQUENCY,
+	/** -sc */
+	LS_SORT_BY_CHANNELS,
+	/** -si */
+	LS_SORT_BY_IMAGE_ID,
+	/** -sy */
+	LS_SORT_BY_LYRICS_ID,
+	/** -sb */
+	LS_SORT_BY_BITRATE,
+	/** -sd */
+	LS_SORT_BY_DURATION,
+	/** -sa */
+	LS_SORT_BY_AUDIO_FORMAT,
+	/** -sh */
+	LS_SORT_BY_HASH,
+};
+
+/** The different listing modes of the ls command. */
 enum ls_listing_mode {
+	/** Default listing mode. */
 	LS_MODE_SHORT,
+	/** -l or -ll */
 	LS_MODE_LONG,
+	/** -lv */
 	LS_MODE_VERBOSE,
+	/** -lm */
 	LS_MODE_MBOX
 };
 
+/** The flags accepted by the ls command. */
 enum ls_flags {
+	/** -p */
 	LS_FLAG_FULL_PATH = 1,
+	/** -a */
 	LS_FLAG_ADMISSIBLE_ONLY = 2,
+	/** -r */
 	LS_FLAG_REVERSE = 4,
 };
 
+/**
+ * The size of the individual output fields of the ls command.
+ *
+ * These depend on the actual content being listed. If, for instance only files
+ * with duration less than an hour are being listed, then the duration with is
+ * made smaller because then the duration is listed as mm:ss rather than
+ * hh:mm:ss.
+ */
 struct ls_widths {
+	/** size of the score field. */
 	unsigned short score_width;
+	/** size of the image id field. */
 	unsigned short image_id_width;
+	/** size of the lyrics id field. */
 	unsigned short lyrics_id_width;
+	/** size of the bitrate field. */
 	unsigned short bitrate_width;
+	/** size of the frequency field. */
 	unsigned short frequency_width;
+	/** size of the duration field. */
 	unsigned short duration_width;
+	/** size of the num played field. */
 	unsigned short num_played_width;
 };
 
+/** Data passed to the different compare functions (called by qsort()). */
 struct ls_data {
+	/** Usual audio format handler information. */
 	struct audio_format_info afhi;
+	/** Audio file selector information. */
 	struct afs_info afsi;
+	/** The full path of the audio file. */
 	char *path;
+	/** The score value (if -a was given). */
 	long score;
+	/** The sha1 hash of audio file. */
 	HASH_TYPE *hash;
 };
 
-- 
2.39.2