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"@}. *!