[RFC] - eliminate boilerplate function documentation

[coke]

In the beginning (or slightly thereafter) there was a test to insure that c function documentation existed.

Then, rather than actually add documentation to make the test pass, placeholder documentation was added in many locations to make the test pass.

Except now the functions still aren't documented, the test still checks for missing docs, not boilerplate docs, so you have to resort to searching for the boilerplate, making the test useless...

Unless I hear a good objection, I'm going to rip out any of the boilerplate docs so we can start using t/codingstd/c_function_docs.t again.

FYI: that test is now run as a TODO'd test as part of the normal 'make codetest'

[whiteknight]

I'm not against this per se, but I think it's going to cause a lot of problems in the short term. In my last examination, there were a very large number of functions that weren't documented. If we remove the boilerplate documentation, we're basically guaranteeing that the test will fail in the foreseeable future.

[coke]

Thats kind of my point. The test should be failing. Things aren't documented and the test says they should be. Saying "this isn't documented" is not documentation.

And it won't actually be failing, it's todo'd. (Until recently it was nearly never run and was failing).

[coke]

This is a basically a duplicate of TT #324.

Closing...