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.