Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.javascript > #21496

Re: JS documentation generators

Show all headers | View raw

On 2013-09-30 09:32, dhtml wrote:
> Doc generators force comment clutter. The comments can and will fall
> out of sync when the code is refactored.

I don't agree with that. The doc blocks are right above the part that's
being modified. If you change the signature of a function and can't
remember to update the API docu even when it's right in front of your
eyes, then no documentation system is going to work for you.

> Comments should explain why, not what.
> 
> The code itself explains what it does.

That's what inline comments are for. Doc blocks are for generating an
API reference. Sure, some projects work fine without documentation; you
just tell those who are interested to read the code and hack away. But
when you're writing a library or a framework, your users or clients
_will_ expect a reference. They don't want to spend hours digging
through all that low level stuff, they want an overview of what can be
called, and how. You can either let the reference be generated
automatically, or write it down in separate documents. Which do you
think is better suited to keep the documentation from going out of sync?

> I am pretty good at cleaning up code [snip]

That's good for you, but clean code and a comprehensive documentation
are not mutually exclusive.

- stefan

Back to comp.lang.javascript | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

JS documentation generators Stefan Weiss <krewecherl@gmail.com> - 2013-09-19 02:31 +0200
  Re: JS documentation generators John Harris <niam@jghnorth.org.uk.invalid> - 2013-09-19 11:41 +0100
  Re: JS documentation generators Cezary Tomczyk <cezary.tomczyk@gmail.com> - 2013-09-19 15:08 +0200
    Re: JS documentation generators Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2013-09-19 17:11 +0200
      Re: JS documentation generators Cezary Tomczyk <cezary.tomczyk@gmail.com> - 2013-09-19 20:35 +0200
        Re: JS documentation generators Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2013-09-19 23:00 +0200
  Re: JS documentation generators Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2013-09-19 17:55 +0200
  Re: JS documentation generators Christoph Michael Becker <cmbecker69@arcor.de> - 2013-09-19 18:03 +0200
  Re: JS documentation generators Aaron Sawyer <aaron.sawyer.NOSPAM@deltaware.com> - 2013-09-19 17:03 -0300
  Re: JS documentation generators Stefan Weiss <krewecherl@gmail.com> - 2013-09-30 02:24 +0200
  Re: JS documentation generators dhtml <dhtmlkitchen@gmail.com> - 2013-09-30 00:32 -0700
    Re: JS documentation generators Dr J R Stockton <reply1300@merlyn.demon.co.uk.invalid> - 2013-10-01 19:44 +0100
    Re: JS documentation generators Stefan Weiss <krewecherl@gmail.com> - 2013-10-02 05:33 +0200
      Re: JS documentation generators Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2013-10-02 10:55 +0200
      Re: JS documentation generators John Harris <niam@jghnorth.org.uk.invalid> - 2013-10-02 14:53 +0100

csiph-web