On Thursday, 18 August 2016 at 15:12:52 UTC, H. S. Teoh wrote:
Nah, this kind of so-called "documentation" is no better than
reading the code itself. It's just like code comments that
basically repeat what the code does, which is useless because
you can already read the code.
What you want are comments / docs that explain things that are
*not*
immediately obvious from the code, such as:
- High-level discussion of *why* this code does what it does;
- Relevant examples of *how* to use it, in the context of what
it was
intended for (i.e., not just a dumb `auto x = myFunc(123);`
which says
nothing about how to use it in real life).
- *When* to use this code, and when not to use it.
- Any gotchas to watch out for (e.g. this function may return
the wrong
result if the input is poorly-conditioned)
- What algorithm(s) are used to compute the result, and why said
algorithms were chosen, their advantages / disadvantages, etc.
Even more obvious parts of the docs also need proper
explanation. For example, compare:
/**
* Repeats a string.
* Params:
* x = a string
* y = an int
* Returns: a string.
*/
string repeat(string x, int y) { ... }
However, this would be very useful as a stub. To write "Repeats a
string by the specified number of times." is trivial. Often a
function can be explained in one or two sentences, like "Saves
output as WAV file. Returns true on success, otherwise false.".
The rest is a real pita. All that boilerplate for
bool saveWAV(string path)
{
// ...
if (...)
return true;
return false
}
That's the real killer. Hey, if dmd can generate files with code
coverage, it could generate files with doc stubs.
