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

Groups > comp.lang.javascript > #21497

Re: JS documentation generators

Show key headers only | View raw

Stefan Weiss wrote:

> 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.

ACK.  Good editors like Eclipse JSDT even partially generate and update the 
documentation comments for you.  Just type /**<RET> above a function, or 
press Ctrl|Cmd+Shift+J (or Alt+Shift+J¹) when the text cursor is on a 
function name.  For example, in the best case the former will generate

  /**
   * _
   * @param bar
   * @param baz
   * @returns {Number}
   */
  function foo (bar, baz)
  {
    return 42;
  }

from

  function foo (bar, baz)
  {
    return 42;
  }

where the text cursor is placed where the “_” is.  (AFAICS @return appears 
to work better than @returns with JSDT, so you should correct that minor 
problem manually.  My generator will support both forms the same way, but 
might issue a configurable warning for the latter.)

And type Ctrl+1¹, then select “Rename in file” (which renames only locally 
if the symbol is recognized as a local one) or type Ctrl+2, R¹ for direct 
access.  In the best case, if you do this on “baz” and type bla<RET>, this 
will change

  /**
   * Frobnicates this object
   * 
   * @param {Object} bar
   *   Frobnication snark
   * @param {String} baz
   *   Frobnication boojum
   * @return {Number}
   *   The Answer frobnicated on this object.
   */
  foo: function (bar, baz) {
    return bar[baz](this, 42);
  }

to

  /**
   * Frobnicates this object
   * 
   * @param {Object} bar
   *   Frobnication snark
   * @param {String} bla
   *   Frobnication boojum
   * @return {Number}
   *   The Answer frobnicated on this object.
   */
  foo: function (bar, bla)
  {
    return bar[bla](this, 42);
  }

(you should see the changes happening as you type).

>> 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.

Not only that.  They also help the IDE to help you write proper code.  For 
example, Eclipse supports code completion (Ctrl+Space¹) with displaying 
documentation comments next to the suggestion when you select it, displays 
the documented or inferred types in the “Outline” view (which can be used 
for navigation in several ways), and can display the formatted documentation 
when you hover over a symbol, or in the “Documentation” view when you have 
the text cursor on a symbol².  Return type inference and return type 
documentation detection are not always reliable (and currently cannot be 
disabled AFAIK), but can be useful as well.

<http://wiki.eclipse.org/JSDT>

(Everything that has “this” in it or is documented as a @type is currently 
treated like a Java class.  This allows you to diffentiate between “private” 
properties in constructors and prototype closures, and instance and 
prototype properties in the ”Outline” view.  See JSX for example code.)

______
¹ Most if not all keyboard shortcuts are configurable in Eclipse per context
  (I have Ctrl+F as “Find” for “Editing Text”, and as “Find File” for
  “Windows” like in the “Project Explorer”; YMMV).  Shortcut collisions are
  detected while configuring.  (Mac users: replace “Ctrl” with “Cmd” here.)
² Do not put the “Documentation” view to front while modifying files > 1000
  LOCs; a lot of heap memory will be used that can make Eclipse not
  responding or responding slowly.  In general, only put it to front after
  you edited because the changes are live.
-- 
PointedEars

Twitter: @PointedEars2
Please do not Cc: me. / Bitte keine Kopien per E-Mail.

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