sysmo-bts
/
barebox
9
0
Fork 0
Code Releases Activity

doc: add macros to unify command help with doxygen 

Currently we have duplicated all the information that appears online in
'help <command>' and in the doxygen documentation. This patch adds some
infrastructure to specify help texts only once and re-use them for the
integrated help as well as for the manual.

Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
This commit is contained in:
Robert Schwebel 2010-07-12 18:03:05 +02:00 committed by Sascha Hauer
parent c84a37d52b
commit 511c5d8d0c
3 changed files with 113 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Doxyfile
View File

@ -575,7 +575,7 @@ IMAGE_PATH =
# to standard output. If FILTER_PATTERNS is specified, this tag will be
# ignored.
INPUT_FILTER =
INPUT_FILTER = "awk -f scripts/doxy_filter.awk"
# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
# basis. Doxygen will compare the file name with each pattern and apply the

9
include/command.h
View File

@ -89,6 +89,15 @@ const struct command __barebox_cmd_##_name \
#define BAREBOX_CMD_END \
};
#define BAREBOX_CMD_HELP_START(_name) \
static const __maybe_unused char cmd_##_name##_help[] =
#define BAREBOX_CMD_HELP_USAGE(_name) "Usage: " _name
#define BAREBOX_CMD_HELP_SHORT(_text) _text
#define BAREBOX_CMD_HELP_OPT(_opt, _desc) _opt "\t" _desc
#define BAREBOX_CMD_HELP_TEXT(_text)
#define BAREBOX_CMD_HELP_END ;
#ifdef CONFIG_LONGHELP
#define BAREBOX_CMD_HELP(text) .help = text,
#else

103
scripts/doxy_filter.awk Normal file
View File

@ -0,0 +1,103 @@
#!/usr/bin/awk
/BAREBOX_CMD_HELP_START[[:space:]]*\((.*)\)/ {
this_opt = 0;
my_usage = "";
my_short = "";
my_cmd = gensub("BAREBOX_CMD_HELP_START[[:space:]]*\\((.*)\\)", "\\1", "g");
this_text = 0;
delete(my_text);
delete(my_opts);
next;
}
/BAREBOX_CMD_HELP_USAGE[[:space:]]*\((.*)\)/ {
$0 = gensub("<", "\\&lt;", "g");
$0 = gensub(">", "\\&gt;", "g");
$0 = gensub("BAREBOX_CMD_HELP_USAGE[[:space:]]*\\((.*)\\)", "\\1", "g");
$0 = gensub("\\\\n", "", "g");
my_usage = gensub("\"", "", "g");
next;
}
/BAREBOX_CMD_HELP_SHORT[[:space:]]*\((.*)\)/ {
$0 = gensub("<", "\\&lt;", "g");
$0 = gensub(">", "\\&gt;", "g");
$0 = gensub("BAREBOX_CMD_HELP_SHORT[[:space:]]*\\((.*)\\)", "\\1", "g");
$0 = gensub("\\\\n", "", "g");
my_short = gensub("\"", "", "g");
next;
}
/BAREBOX_CMD_HELP_OPT[[:space:]]*\([[:space:]]*(.*)[[:space:]]*,[[:space:]]*(.*)[[:space:]]*\)/ {
$0 = gensub("<", "\\&lt;", "g");
$0 = gensub(">", "\\&gt;", "g");
$0 = gensub("@", "\\\\@", "g");
$0 = gensub("BAREBOX_CMD_HELP_OPT[[:space:]]*\\([[:space:]]*\"*(.*)\"[[:space:]]*,[[:space:]]*\"(.*)\"[[:space:]]*\\)", \
"<tr><td><tt> \\1 </tt></td><td>\\&nbsp;\\&nbsp;\\&nbsp;</td><td> \\2 </td></tr>", "g");
$0 = gensub("\\\\n", "", "g");
my_opts[this_opt] = gensub("\"", "", "g");
this_opt ++;
next;
}
/BAREBOX_CMD_HELP_TEXT[[:space:]]*\((.*)\)/ {
$0 = gensub("<", "\\&lt;", "g");
$0 = gensub(">", "\\&gt;", "g");
$0 = gensub("BAREBOX_CMD_HELP_TEXT[[:space:]]*\\((.*)\\)", "\\1", "g");
$0 = gensub("\\\\n", "<br>", "g");
my_text[this_text] = gensub("\"", "", "g");
this_text ++;
next;
}
/BAREBOX_CMD_HELP_END/ {
printf "/**\n";
printf " * @page " my_cmd "_command " my_cmd "\n";
printf " *\n";
printf " * \\par Usage:\n";
printf " * " my_usage "\n";
printf " *\n";
if (this_opt != 0) {
printf " * \\par Options:\n";
printf " *\n";
printf " * <table border=\"0\" cellpadding=\"0\">\n";
n = asorti(my_opts, my_opts_sorted);
for (i=1; i<=n; i++) {
printf " * " my_opts[my_opts_sorted[i]] "\n";
}
printf " * </table>\n";
printf " *\n";
}
printf " * " my_short "\n";
printf " *\n";
n = asorti(my_text, my_text_sorted);
if (n > 0) {
for (i=1; i<=n; i++) {
printf " * " my_text[my_text_sorted[i]] "\n";
}
printf " *\n";
}
printf " */\n";
next;
}
/^.*$/ {
print $0;
}