*** Bug 434177 has been marked as a duplicate of this bug. ***

Some additional suggestion from bug 434177: It would be nice if this thing was run on make check, not only on distcheck.

Created attachment 93276 [details]
run documentation tests

put this into gtk-doc.make:

TESTS=<prefix>/gtkdoc-check
e.g.:
TESTS=/opt/gnome/bin/gtkdoc-check

and exactly this is the problem. If its not a fully patch make check tries to *make* and run it localy. Any ideas?

What about this hack for gtkdoc.make

TESTS = gtkdoc-check

gtkdoc-check:
	cp `which gtkdoc-check` ./

CLEANFILES = ... gtkdoc-check

FWIW, this is the script I use in pango:

#!/bin/sh

LANG=C

test -z "$srcdir" && srcdir=.
status=0

if ! test -f pango-undocumented.txt -a -f pango-unused.txt; then
        echo At least one of pango-undocumented.txt and pango-unused.txt not found.
        echo Skipping test.
        exit 0
fi

status=0

unused=`cat pango-unused.txt`
if test -n "$unused"; then
        echo Unused documentated symbols:
        cat pango-unused.txt
        status=1
fi
if ! grep '^0 symbols incomplete' pango-undocumented.txt >/dev/null ||
   ! grep '^0 not documented'     pango-undocumented.txt >/dev/null; then
        echo Incomplete or undocumented symbols:
        cat pango-unused.txt
        status=1
fi

exit $status

(In reply to comment #5)
> FWIW, this is the script I use in pango:
> 
> #!/bin/sh
> 
> LANG=C
> 
> test -z "$srcdir" && srcdir=.
> status=0
> 
> if ! test -f pango-undocumented.txt -a -f pango-unused.txt; then
>         echo At least one of pango-undocumented.txt and pango-unused.txt not
> found.
>         echo Skipping test.
>         exit 0
> fi
> 
> status=0
> 
> unused=`cat pango-unused.txt`
> if test -n "$unused"; then
>         echo Unused documentated symbols:
>         cat pango-unused.txt
>         status=1
> fi
> if ! grep '^0 symbols incomplete' pango-undocumented.txt >/dev/null ||
>    ! grep '^0 not documented'     pango-undocumented.txt >/dev/null; then
>         echo Incomplete or undocumented symbols:
>         cat pango-unused.txt

Humm, this one should be cat pango-undocumented.txt



>         status=1
> fi
> 
> exit $status
> 

@Behdad, my script works in a similar way. Main issue is the invocation from the gtkdoc.make. I also mimiced the output from check in the hope that its then easier to treat in in the test-status page on build.gnome.org.

Please write it in Perl.

The rest of gtk-doc is written in Perl and it's much easier to write code like this portably in Perl than in shell.  I won't go into great lengths as what can go wrong in various shells and with various version of Unix text tools (and don't imagine anything exotic, run it on Ubuntu where all text tools are the GNU versions, just /bin/sh is dash instead of bash -- running it on *BSD would be much more fun).

Also, I am probably not the only one with spaces around `=' in my Makefiles:

DOC_MODULE = libgwyddion

This does not work, the script requires

DOC_MODULE=libgwyddion

yes we can rewrite in in perl. The more critical point is the invocation and that need to be solved/agreed with before.

OK, invocation.

1. Extend gtk-doc.m4 with

AC_PATH_PROGS(GTKDOC_CHECK,gtkdoc-check,)

2. Use

TESTS = $(GTKDOC_CHECK)

in the makefile.

The thing I am missing in this discussion is: how is one supposed enable/disable this?  Because not everyone probably wants missing documentation make `make check' fail.

The easiest way seems to be putting the TESTS line not into gtk-doc.make, but into the sample Makefile.am, commented out and commented, and letting the user uncomment it at his discretion.

Question: How do we encourage projects to use this feature?
I think maintainers should not be annoyed by make check failing, but should want to use this feature.

Just making projects with non-updated documentation suddenly fail on make check obviously does not seem like a good idea. But you want to get those projects to use it that take care of their documentation. This includes both projects that already use gtk-doc and new projects.

For existing projects, I have no idea how to solve it, maybe posting it to various lists and blogs.

For new projects I'd suggest enabling the check automatically and having an easy way to opt out. I think it's a reasonable assumption that people use gtk-doc to write complete and good documentation, so supporting this should be the default behavior.

(In reply to comment #11)
> For new projects I'd suggest enabling the check automatically and having an
> easy way to opt out. I think it's a reasonable assumption that people use
> gtk-doc to write complete and good documentation, so supporting this should be
> the default behavior.

I don't think it's a reasonable assumption that a typical *new* project has 100% coverage of API documentation, not even that documenting every obscure exported symbol is well spent effort in the `0.1' stage.

I've committed it. When 1.9 comes out I will do some blogging to tech maintainer what new things they can do.
@Yeti, sorry for keeping it a shell script. I fixed the docmodule matching though.

2007-08-10  Stefan Kost  <ensonic@users.sf.net>

	* examples/Makefile.am:
	  Add commented out TESTS.

	* gtk-doc.m4:
	  Check for location of gtkdoc-check.

	* Makefile.am:
	* gtkdoc-check:
	  Test doc status and print result in check like layout.

If I rewrite it in Perl, will you replace it?

Yes, I will :) Lets see how much simpler you'll get it.

(In reply to comment #15)
> Yes, I will :) Lets see how much simpler you'll get it.

Simpler, well, that was not exactly the primary goal.  Correct and portable were.

Created attachment 93451 [details]
alternate gtkdoc-check (in Perl)

Looks good, but should probably be move to .in with the @PERL@ replacement for line 1.

Cannot open tester-unused.txt: No such file or directory

The grep function should not fail for optional files.

Created attachment 93507 [details]
alternate gtkdoc-check (in Perl)

Don't die in CheckEmpty if the file does not exist, nonexistent files are as good as empty.  Fixed inversion of some failure conditions in the rate calculation.

(In reply to comment #18)
> Looks good, but should probably be move to .in with the @PERL@ replacement for
> line 1.

Yes, this can be easily changed when it's being added to the repo.  The plain form is better for testing.

2007-08-12  Stefan Kost  <ensonic@users.sf.net>

	* Makefile.am:
	* configure.in:
	* gtkdoc-check:
	* gtkdoc-check.in:
	  Replacing my shell based test script by Davids perl based one. Add
	  licence, copyright and docs header. Integrate with build.