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
