documentation_test.sh check fails

[Jari Häkkinen]

make check
...
FAIL: documentation_test.sh

Verbosity gives

./documentation_test.sh -v
/Users/jari/projects/yat/yat/normalizer/CubicSplineNormalizer.cc:30 Warning: Member CSN (typedef) of namespace theplu::yat::normalizer is not documented.
/Users/jari/projects/yat/yat/normalizer/CubicSplineNormalizer.h:45 Warning: Member CubicSplineNormalizer(const utility::VectorConstView &target) (function) of class theplu::yat::normalizer::CubicSplineNormalizer is not documented.
/Users/jari/projects/yat/yat/normalizer/CubicSplineNormalizer.h:50 Warning: Member operator()(InputIterator first, InputIterator last, OutputIterator result) const  (function) of class theplu::yat::normalizer::CubicSplineNormalizer is not documented.

[Peter]

This seems to be specific for stuff you have not committed yet, so I don't see the need for a ticket.

[Jari Häkkinen]

Ah, you are right. I'll make sure that the documentation check passes before checking in cubic spline. I'll close this ticket when it is done.

[Jari Häkkinen]

So, the problem is that doxygen reports missing documentation. Does this mean that we must created documentation? I know we should but the documentation requires us to created docs. Of course, I only added a todo document block resolving the issue but I suppose that is not the idea with the test.

[Peter]

I am not sure whether text above is a question or just free thoughts.

Experience tells us that we are sloppy about documenting and the errors from doxygen are accumulating over time. Not only that docs are missing, but also parsing errors of all kinds. In fact several times we have had "fixing doxygen issues" campaigns, which is a pain. This test is an attempt to avoid that to happen again. We all know that the best time to document is right after (or before) coding.

It is tempting to think "I will document next month when things have slowed down a bit", just like it is tempting to look for that coffin of gold at the end of the rainbow.

As you already noticed the test doesnt check that the docs are correct and clear.

[Jari Häkkinen]

Replying to peter:

I am not sure whether text above is a question or just free thoughts.

Well, I think I just wanted to start a discussion. I actually looked in several places if there was a direct requirement that developers write documentation ... I could not find anything in the obvious places http://dev.thep.lu.se/yat/wiki/CodingStyle, source:trunk/README​, and source:trunk/README.developer​. There is only one indirect requirement, make check must work. Obviously I failed on this step and did not understand the problem until now.

Experience tells us that we are sloppy about documenting and the errors from doxygen are accumulating over time. Not only that docs are missing, but also parsing errors of all kinds. In fact several times we have had "fixing doxygen issues" campaigns, which is a pain. This test is an attempt to avoid that to happen again. We all know that the best time to document is right after (or before) coding.

It is tempting to think "I will document next month when things have slowed down a bit", just like it is tempting to look for that coffin of gold at the end of the rainbow.

As you know, I am all for documentation even when there is a lot of things to do in a project. Actually, in stressful time I believe it is even more important to document ... it will help when you have to fix the mess you created.

As you already noticed the test doesnt check that the docs are correct and clear.

Of course, I am writing code not documentaion. For some reason I don't like the message 1 test failed after a 'make check'. However, being forced to add phony documentation is a very concious act ... you now you are cheating.

The conclusion is that we should add a note somewhere telling the developers that tests will fail because of missing documentation.

[Peter]

Replying to jari:

Replying to peter:

I am not sure whether text above is a question or just free thoughts.

Well, I think I just wanted to start a discussion. I actually looked in several places if there was a direct requirement that developers write documentation ... I could not find anything in the obvious places http://dev.thep.lu.se/yat/wiki/CodingStyle, source:trunk/README​, and source:trunk/README.developer​. There is only one indirect requirement, make check must work.

I can't even find that requirement. I think I prefer to collect stuff in README.developer. Perhaps we should move the content in wiki page CodingStyle? to the README.developer.

Obviously I failed on this step and did not understand the problem until now.

We should encourage people to re-run the failed test with flag '-v'. That helps when not understanding the problem.

Experience tells us that we are sloppy about documenting and the errors from doxygen are accumulating over time. Not only that docs are missing, but also parsing errors of all kinds. In fact several times we have had "fixing doxygen issues" campaigns, which is a pain. This test is an attempt to avoid that to happen again. We all know that the best time to document is right after (or before) coding. As you already noticed the test doesnt check that the docs are correct and clear.

Of course, I am writing code not documentaion. For some reason I don't like the message 1 test failed after a 'make check'.

Again we should encourage people to re-run the failed test in verbose mode.

However, being forced to add phony documentation is a very concious act ... you now you are cheating.

yeah it's... well nevermind.

The conclusion is that we should add a note somewhere telling the developers that tests will fail because of missing documentation.

I would go for README.developer. A short paragraph about testing and that tests must pass when committing, and that there is a test, documetation_test.sh, that checks that docs are OK.

[Jari Häkkinen]

I'll add a paragraph. Should we move CodingStyle? into README.developer?

[Peter]

Replying to jari:

I'll add a paragraph. Should we move CodingStyle? into README.developer?

Yes I think so.

[Peter]

Please see ticket:392 as well.

[Peter]

(In [1640]) adding some text on how to use the test suite - and also some rules I think we have decided on. refs #458

[Peter]

(In [1674]) merging wiki:CodingStyle? into README.developer - refs #458

[Jari Häkkinen]

(In [1721]) Addresses #458. Added a paragraph on subversion, added information on documentation test, spellchecked file.