X-Git-Url: http://git.tuebingen.mpg.de/?p=adu.git;a=blobdiff_plain;f=select.c;h=44178805122bbd2afddaceb0d15de4918cb95d58;hp=d6585857e62e32d2e0abc2da8bb0ff6d6683779a;hb=22a0aa79753b19604a6fa4273f1479ef71dbf06d;hpb=44bb864e9d02f765064645b4e70d48b8c8113c48

diff --git a/select.c b/select.c
index d658585..4417880 100644
--- a/select.c
+++ b/select.c
@@ -942,7 +942,33 @@ static int setup_format_string(char *fmt, struct format_info **fi)
 	return parse_format_string(fmt, atoms, fi);
 }
 
-/* return: < 0: error, >0: OK, == 0: help given */
+/**
+ * Parse a given format string.
+ *
+ * \param string The format string to parse.
+ * \param params gengetopt parameters.
+ * \param admissible_uids The array of admissible uid ranges.
+ * \param fi The format info to be used with format_items().
+ *
+ * If \a string is not \p NULL, it is broken down into its components using
+ * \ref create_argv() and the resulting argument vector is passed together with
+ * \a params to gengetopt's command line parser. If --help or --detailed-help
+ * was specified in \a string, the corresponding help text is printed and the
+ * function returns zero.
+ *
+ * Otherwise, any --uid or --user options are parsed and transformed into an
+ * array of admissible uids which is returned via \a admissible_uids.
+ *
+ * Finally, the format string given by --format (or the default format string
+ * for the given select mode if no --format option was given in \a string) is
+ * parsed as well resulting in a format_info structure which is returned via
+ * \a fi. The caller uses the \a fi pointer later to format each output line.
+ *
+ * \return Negative on errors, zero if --help or --detailed-help was given,
+ * positive otherwise.
+ *
+ * \sa format_items().
+ */
 int parse_select_options(char *string, struct select_cmdline_parser_params *params,
 		struct uid_range **admissible_uids, struct format_info **fi)
 {