X-Git-Url: http://git.tuebingen.mpg.de/?p=adu.git;a=blobdiff_plain;f=format.h;h=1e795c6c03a3bd29c4f1049c271d7d2a90bd547c;hp=2b8b7f20e5999c8b27a44a2c9c8c4640ca3ae81b;hb=cd5cfb4c2dbbf5615c78d1e439f0cbfb08437b43;hpb=bd06800e612996d0c4b4c2ec52646a842d301452

diff --git a/format.h b/format.h
index 2b8b7f2..1e795c6 100644
--- a/format.h
+++ b/format.h
@@ -1,20 +1,74 @@
-/* format.h */
-enum atom_type {AT_STRING, AT_ID, AT_COUNT, AT_SIZE};
 /*
- * STRING: %(foo:a:w)
- * (U)INT: %(foo:a:w:u)
+ * Copyright (C) 2008 Andre Noll <maan@tuebingen.mpg.de>
+ *
+ * Licensed under the GPL v2. For licencing details see COPYING.
+ */
+
+/** \file format.h \brief Exported symbols from \p format.c. */
+
+/** The possible types of format string directives (aka atoms). */
+enum atom_type {
+	/** String, supports alignment and width. */
+	AT_STRING,
+	/** Used for user IDs, supports alignment and width. */
+	AT_ID,
+	/**
+	 *  Used for number of files/directories, supports alignment,
+	 *  width, unit.
+	 */
+	AT_COUNT,
+	/**
+	 * Used for number of bytes. Like \p AT_COUNT, but the unit is
+	 * treated differently: By default, 1024 is used as the base,
+	 * and low numbers get a "b" (bytes) appended which does not make
+	 * sense for counters.
+	 */
+	AT_SIZE
+};
+
+/**
+ * One format string directive.
+ *
+ * Each application must define its own set of valid atoms as an array
+ * of struct atom. The \ref parse_format_string() function takes a format
+ * string and the array of valid atoms and returns an opaque pointer to
+ * a struct \a format_info.
+ *
+ * At a later time the application may pass the \a format_info pointer
+ * together with the current value for each atom to \a format_items() which
+ * returns these values, formated according to the format string which has
+ * been passed to parse_format_string() previously.
+ *
+ * Usually, the application will call parse_format_string() only once, but
+ * format_items() many times.
  */
 struct atom {
+	/** The name of the directive. */
 	const char const *name;
+	/** Its type. */
 	enum atom_type type;
 };
 
+/**
+ * The current value of one atom.
+ *
+ * An array of this type, whose entries must match the array of valid atoms,
+ * may be passed to format_items() to obtain a formated string.
+ */
 union atom_value {
+	/** Used for atoms of type string. */
 	char *string_value;
+	/** Used for atoms not of type string. */
 	long long unsigned num_value;
 };
 
-struct format_info; /* opaque */
-int parse_format_string(char *fmt, struct atom *atoms, struct format_info **result);
+/**
+ * The details of this structure are only relevant to the functions in \p
+ * format.c.
+ */
+struct format_info;
+
+int parse_format_string(char *fmt, struct atom *atoms,
+		struct format_info **result);
 char *format_items(struct format_info *info, union atom_value *values);
 void free_format_info(struct format_info *info);