Ticket #493 (closed RFC: duplicate)

Opened 6 years ago

Last modified 6 years ago

[RFC] - eliminate boilerplate function documentation

Reported by: coke Owned by: coke
Priority: normal Milestone: 1.1
Component: docs Version:
Severity: medium Keywords:
Cc: Language:
Patch status: Platform:

Description

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'

Change History

Changed 6 years ago by 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.

Changed 6 years ago by 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).

Changed 6 years ago by coke

  • status changed from new to closed
  • resolution set to duplicate

This is a basically a duplicate of TT #324.

Closing...

Note: See TracTickets for help on using tickets.