[ccan] ccan lint, doxygen and unit tests

[Rusty Russell]

On Wednesday 25 February 2009 20:03:56 Tim Post wrote:
> So, is a score of 4/5  (or after GSOC 6/10) acceptable, if the only
> thing that lint complains about is whitespace?

Heh, the whitespace test is only in there because it was a trivial
example to write :)

I don't think it will be desirable for a non-trivial module to get a perfect ccanlint score as ccanlint grows: it's always better to use your common sense.

> Secondly, can we introduce a central doxyfile (I'm happy to maintain it)
> so that documentation per module can be extracted? Modules that have
> such comments can be easily added to this file in a uniform way.

There's a tools/doc-extract which does this; I use it to generate the web pages (and also want to use it for ccanlint to actually test the embedded examples).

> Finally, we have unit tests. Could someone comment a function like this
> and have them generated automagically? (Rusty, please forgive the winged
> comment, I'm making it compatible with doxygen)

See above; I agree this is a direction we want to go.  I think we'll always want unit tests as we have, but I do believe there should be a (more human readable!) option for the examples to double as tests, eg:

	Example:
		printf("Alignment of char is %u\n", ALIGNOF(char));

	Gives:
		Alignment of char is 1

Of course, the v. v. clever Ccanlint Which Will Exist will figure out how to wrap that code fragment so it compiles and runs.

> 1 - It breaks the tests totally at build time if someone forgets
> something

For me, ccanlint is to be the universal check: checking for everything from testsuite regressions, to testsuite coverage, to comment typos.

> 2 - Its much easier to keep up on unit testing, (if done correctly) with
> very little time involved.

You get what you measure: that's why I want ccanlint to do coverage analysis.

Here's the conflict I see:
1) We want people to use the code.  Cryptic comments in headers are scary,
   but testing gives more confidence in the code.
2) We want people to contribute code.  YA format language adds barriers.

So I think we're best to aim for clear useful examples, which also happen to be automatically testable.

Cheers,
Rusty.