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

[H. S. Teoh via Digitalmars-d]

On Thu, Aug 18, 2016 at 01:19:13PM +0000, Chris via Digitalmars-d wrote:
[...]
> Isn't there a way to auto-generate a minimal documentation with the
> help of the compiler? As in
> 
> int myFunction(int a, int b)
> {
>   if (a > -1)
>     return a + b;
>   return -1;
> }
> 
> // auto-gen:
> Returns `int`, if `a` is greater than -1, else returns -1.
> Parameters: `int`, `int`; Returns `int`.
> 
> Something like that.

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) { ... }

versus:

	/**
	 * Repeats a string by the specified number of times.
	 * Params:
	 *	x = the string to repeat
	 *	y = the number of times to repeat the string
	 * Returns: the input string repeated y times.
	 */
	string repeat(string x, int y) { ... }

The first example has completely worthless docs, because it says nothing
that the function signature itself doesn't already tell you. The second
is better because it describes what the parameters are supposed to
signify, and defines the result more precisely.

Autogenerated docs give you the first kind of docs. You need human
effort to write the second kind.


T

-- 
In theory, there is no difference between theory and practice.