I think extract_autodoc should exit with a non-0 exitcode whenever it
produces an error message. Right now, it doesn't, which can cause
documentation markup errors to go unnoticed.
When running "make documentation" on the current tip of the 8.1
branch, (commit 73945f040279bfe66d), you get this error message:
> /home/cederp/rgit/pike/src/cpp.c:5918..5921: DocParser error: @expr{ without matching @}
>
> ERROR: <Invalid error container: Tools.AutoDoc.AutoDocError(SourcePosition(File: /home/cederp/rgit/pike/src/cpp.c, lines: 5918..5921), "DocParser", "@expr{ without matching @}")>
The resulting
./build/linux-3.13.0-153-generic-x86_64/doc_build/src/cpp.c.xml file
contains a single newline. However, the extract_autodoc command used
exit code 0, so it didn't fail. (In this case, a later make command
fails, but I've seen cases where the entire build succeeds -- but
maybe that wasn't in the Pike tree.)
The patch below is one way of making sure that extract_autodoc fails.
Maybe there are better ways.
diff --git a/lib/modules/Tools.pmod/Standalone.pmod/extract_autodoc.pike b/lib/modules/Tools.pmod/Standalone.pmod/extract_autodoc.pike
index a3fb82645c..a346f9a132 100644
--- a/lib/modules/Tools.pmod/Standalone.pmod/extract_autodoc.pike
+++ b/lib/modules/Tools.pmod/Standalone.pmod/extract_autodoc.pike
@@ -717,6 +717,8 @@ string extract(string filename, string imgdest,
if (!verbosity)
;
werror("\nERROR: %s\n", describe_error(err));
+ if (!(flags & Tools.AutoDoc.FLAG_KEEP_GOING))
+ exit(1);
// return 0;
}
And the actual documentation markup error is trivial to fix:
diff --git a/src/cpp.cmod b/src/cpp.cmod
index 3b98d89746..440dceb3c7 100644
--- a/src/cpp.cmod
+++ b/src/cpp.cmod
@@ -5018,7 +5018,7 @@ static void insert_callback_define_no_args(struct object *cpp_obj,
*! it will default to @expr{"-"@}.
*!
*! @param charset
- *! Turn on automatic character set detection if @expr{1}, otherwise
+ *! Turn on automatic character set detection if @expr{1@}, otherwise
*! specifies the character set used by the input.
*! Defaults to @expr{"ISO-10646"@}.
*!