[OT] of [OT] I am a developer and I hate documentation

[Chris via Digitalmars-d]

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.