Path: csiph.com!usenet.pasdenom.info!dedibox.gegeweb.org!gegeweb.eu!nntpfeed.proxad.net!feeder1-2.proxad.net!proxad.net!feeder2-2.proxad.net!newsfeed.arcor.de!newsspool3.arcor-online.net!news.arcor.de.POSTED!not-for-mail
Content-Type: text/plain; charset="UTF-8"
Message-ID: <1997724.5XKlcCFdEn@PointedEars.de>
From: Thomas 'PointedEars' Lahn <PointedEars@web.de>
Reply-To: Thomas 'PointedEars' Lahn <cljs@PointedEars.de>
Organization: PointedEars Software (PES)
Date: Wed, 02 Oct 2013 10:55:50 +0200
User-Agent: KNode/4.10.5
Content-Transfer-Encoding: 8Bit
X-Face: %i>XG-yXR'\"2P/C_aO%~;2o~?g0pPKmbOw^=NT`tprDEf++D.m7"}HW6.#=U:?2GGctkL,f89@H46O$ASoW&?s}.k+&.<b';Md8`dH6iqhT)6C^.Px|[=M@7=Ik[_w<%n1Up"LPQNu2m8|L!/3iby{-]A+#YE}Kl{Cw$\U!kD%K}\2jz"QQP6Uqr],./"?;=4v
Face: iVBORw0KGgoAAAANSUhEUgAAADAAAAAwBAMAAAClLOS0AAAAGFBMVEXTxa4RFk5dUWANED8PFEfy7+MGBiW+n3ZNF/QuAAACaElEQVQ4jVXUwVOcMBQG8Dc7Rc4PUntdWV2uxjDpGaGeozOp1woar4jd5t/v9wLstMwsA/ntlxdCAgUc1hjTc9/JCZfGoo3wG3HdmdAWrIJRHe7GM/TmpY5VFefuVcAkkPbLIaN8rmPmjloyZxgyR3GuJ4K0AGtJ2htz8o7yqikm759fldQXaMpbDzjKAG+8v+AugVTOPO5DOjLvGtUYQwh0CPjnVMyGd+8/GfUB5nLKJDD2aLDh5HYyMDJGDwQIo2ZmZcKbowNmAdB/AzyFhrmF2MHRb0QJJfaAnwGB6orZhoykLzJtGwF/xpYxI1dswomiUj3gTuAIqCn/4C7cULwGNBtwMTk3Y4LfKB5YUaOKBKYtpplm7u0vip8tU1NWWyI/7XdcSuIDoMt6rVHMWT0DbjHPGqDqZVSa6zleLcUTcIKLoMv3ueJluALtAo9B302zPPlrtiVScRdCjXvVh3e3JpYa/jjkuC9N+LrBMlz/eAN4eQijX2EdLo6c5tGGHwLyHFtXk89dDGHwCVhG9T0S/j55AhRZgkMCmUQXJ49TnS1wnQDvw0eAh9ICeMmEFbCnPMFzjAvsWoEWEFdYEx+S0MoUZ1gT1wId8+AF3Bl2OoEu906AUHx5VLw/gXYg/x84loOah/2UYNrgiwSwGO7RfUzVBbx/kgpckumGOi6QirtD6gkLTitbnxNol47S2jVc2vsN5kPqaAHT8uUdAJM4v/DanjYOwmUjWznGfwB7sGtAtor5BgofDuzaRj4kSQAqDakTsKORa3Q3xKi3gE1fhl71KRMqrdZ2AWNNg/YOhQyrVBnb+i+nEg4bsDA+egAAAABJRU5ErkJggg==
Subject: Re: JS documentation generators
Newsgroups: comp.lang.javascript
References: <l1dgkc$46e$1@news.albasani.net> <c3006ee2-3b46-4034-b9f9-40e078424410@googlegroups.com> <l2g46r$use$1@news.albasani.net>
MIME-Version: 1.0
Lines: 115
NNTP-Posting-Date: 02 Oct 2013 10:55:53 CEST
NNTP-Posting-Host: 9c75b39e.newsspool4.arcor-online.net
X-Trace: DXC=?=mQP2G2X5GWDmlTRbh@=I4IUK<Cl32<A4Fo<]lROoRA8kF<OcfhCOK\hWdEekMToMDZm8W4\YJNLb@mF9jNikdEDZIgZChmYcKl=D7BkCL@6@
X-Complaints-To: usenet-abuse@arcor.de
Xref: csiph.com comp.lang.javascript:21497

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.