Opened 11 years ago

Closed 11 years ago

#458 closed defect (fixed)

documentation_test.sh check fails

Reported by: Jari Häkkinen Owned by: Jari Häkkinen
Priority: major Milestone: yat 0.5
Component: test Version: trunk
Keywords: Cc:

Description

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.

Change History (13)

comment:1 Changed 11 years ago by Peter

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

comment:2 Changed 11 years ago by Jari Häkkinen

Status: newassigned

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.

comment:3 Changed 11 years ago by 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.

comment:4 Changed 11 years ago by 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.

comment:5 in reply to:  4 ; Changed 11 years ago by 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.

comment:6 in reply to:  5 Changed 11 years ago by 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.

comment:7 Changed 11 years ago by Jari Häkkinen

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

comment:8 in reply to:  7 Changed 11 years ago by Peter

Replying to jari:

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

Yes I think so.

comment:9 Changed 11 years ago by Peter

Please see ticket:392 as well.

comment:10 Changed 11 years ago by 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

comment:11 Changed 11 years ago by Peter

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

comment:12 Changed 11 years ago by Jari Häkkinen

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

comment:13 Changed 11 years ago by Jari Häkkinen

Resolution: fixed
Status: assignedclosed
Note: See TracTickets for help on using tickets.