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

[H. S. Teoh via Digitalmars-d]

On Thu, Aug 18, 2016 at 03:38:03PM +0000, Chris via Digitalmars-d wrote:
> 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.
[...]

Shouldn't that be the job of the IDE?  If the IDE always generated doc
stubs for non-private functions, that could be good encouragement for
the coder to actually fill it in! Esp. if the stub reads:

	/**
	 * THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
	 * Params:
	 *	x = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
	 *	y = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
	 * Returns: THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
	 */
	int myFunc(int x, int y) { ... }

:-P


T

-- 
"Holy war is an oxymoron." -- Lazarus Long