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

Groups > comp.lang.javascript > #21383 > unrolled thread

JS documentation generators

Back to article view | Back to comp.lang.javascript

Contents

  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

#21383 — JS documentation generators

For those of you who write inline documentation blocks, what do you use
to generate a user-readable API documentation from your source files?

  [ ] JSDoc        <https://github.com/jsdoc3/jsdoc>
  [ ] YUIDoc       <http://yui.github.io/yuidoc/>
  [ ] Docco        <http://jashkenas.github.io/docco/>
  [ ] JSDuck       <https://github.com/senchalabs/jsduck>
  [ ] NaturalDocs  <http://www.naturaldocs.org/>
  [ ] DTK          <https://github.com/wkeese/api-viewer>
  [ ] something else: ____________
  [ ] something only available in my company
  [ ] built my own tool  (URL, if available: ____________)
  [ ] my IDE handles that  (which IDE? which plugin?)
  [ ] I just write the doc blocks, the rest is not my concern
  [ ] this is useless for JavaScript/ECMAScript/...
  [ ] I don't use anything like that, but want to check a box anyway
  [ ] what are inline documentation blocks?
  [ ] inline API documentation is WRONG
  [ ] comments are for the weak
  [ ] your logic is flawed

If I haven't covered all possible choices, just tell me what I missed.

- stefan

[toc] | [next] | [standalone]

#21385

On Thu, 19 Sep 2013 02:31:07 +0200, Stefan Weiss
<krewecherl@gmail.com> wrote:

>For those of you who write inline documentation blocks, what do you use
>to generate a user-readable API documentation from your source files?
  <snip>

>If I haven't covered all possible choices, just tell me what I missed.

I hate doc systems that put a function's comments outside the function
definition. I.e Ones that won't let you do
  
function doit()
  /* Function spec here
  */
{
  ...
}

  John

[toc] | [prev] | [next] | [standalone]

#21387

On 2013-09-19 02:31, Stefan Weiss wrote:
> For those of you who write inline documentation blocks, what do you use
> to generate a user-readable API documentation from your source files?
>
>    [ ] JSDoc        <https://github.com/jsdoc3/jsdoc>
[...]

I use JSDoc.

-- 
Cezary Tomczyk
http://www.ctomczyk.pl/

[toc] | [prev] | [next] | [standalone]

#21388

Cezary Tomczyk wrote:

> On 2013-09-19 02:31, Stefan Weiss wrote:
>> For those of you who write inline documentation blocks, what do you use
>> to generate a user-readable API documentation from your source files?
>>
>>    [ ] JSDoc        <https://github.com/jsdoc3/jsdoc>
> [...]
> 
> I use JSDoc.

Same here (Eclipse JSDT supports it natively to a certain extent), however 
because of its limitations I am working on a documentor of my own, based on 
the same syntax.
 
-- 
PointedEars

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

[toc] | [prev] | [next] | [standalone]

#21392

On 2013-09-19 17:11, Thomas 'PointedEars' Lahn wrote:
[...]
> Same here (Eclipse JSDT supports it natively to a certain extent), however
> because of its limitations I am working on a documentor of my own, based on
> the same syntax.

Any plans to publish it?

-- 
Cezary Tomczyk
http://www.ctomczyk.pl/

[toc] | [prev] | [next] | [standalone]

#21395

Cezary Tomczyk wrote:

> On 2013-09-19 17:11, Thomas 'PointedEars' Lahn wrote:
> [...]
>> Same here (Eclipse JSDT supports it natively to a certain extent),
>> however because of its limitations I am working on a documentor of my
>> own, based on the same syntax.
> 
> Any plans to publish it?

Yes.

-- 
PointedEars

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

[toc] | [prev] | [next] | [standalone]

#21389

Stefan Weiss wrote:

> For those of you who write inline documentation blocks, what do you use
> to generate a user-readable API documentation from your source files?
> 
>   […]
>   [ ] I just write the doc blocks, the rest is not my concern
>   [ ] this is useless for JavaScript/ECMAScript/...
>   [ ] I don't use anything like that, but want to check a box anyway
>   [ ] what are inline documentation blocks?
>   [ ] inline API documentation is WRONG
>   [ ] comments are for the weak
>   [ ] your logic is flawed
> 
> If I haven't covered all possible choices, just tell me what I missed.

YMMD :)

-- 
PointedEars

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

[toc] | [prev] | [next] | [standalone]

#21390

Stefan Weiss wrote:

> For those of you who write inline documentation blocks, what do you use
> to generate a user-readable API documentation from your source files?

[x] JSDoc        <https://github.com/jsdoc3/jsdoc>

I have not even heard of the others.

-- 
Christoph M. Becker

[toc] | [prev] | [next] | [standalone]

#21394

In article <l1dgkc$46e$1@news.albasani.net>, krewecherl@gmail.com 
says...
> 
> For those of you who write inline documentation blocks, what do you use
> to generate a user-readable API documentation from your source files?
> 
>   [ ] JSDoc        <https://github.com/jsdoc3/jsdoc>
>   [ ] YUIDoc       <http://yui.github.io/yuidoc/>
>   [ ] Docco        <http://jashkenas.github.io/docco/>
>   [ ] JSDuck       <https://github.com/senchalabs/jsduck>
>   [X] NaturalDocs  <http://www.naturaldocs.org/>
>   [ ] DTK          <https://github.com/wkeese/api-viewer>
>   [ ] something else: ____________
>   [ ] something only available in my company
>   [ ] built my own tool  (URL, if available: ____________)
>   [ ] my IDE handles that  (which IDE? which plugin?)
>   [ ] I just write the doc blocks, the rest is not my concern
>   [ ] this is useless for JavaScript/ECMAScript/...
>   [ ] I don't use anything like that, but want to check a box anyway
>   [ ] what are inline documentation blocks?
>   [ ] inline API documentation is WRONG
>   [ ] comments are for the weak
>   [ ] your logic is flawed
> 
> If I haven't covered all possible choices, just tell me what I missed.
> 
> - stefan


    [X] NaturalDocs  <http://www.naturaldocs.org/>

The only issue(s) I had with ND were:

1. The inline commentary did not enhance the readability of the code
	1a. a long comment block that ND would parse to generate the 
displayable document (index table, API description), followed 
by/interspersed with
	1b. short (1-15 lines) functions that were the implementation of 
the documented API

2. As nearly as I can tell, I was the only person in that development 
group to use ND, and no other person in that company had any interest in 
inline document generation (there's very little interest in 
documentation at all).

3. ND requires Perl, which is a suspect tool in a Windows-only shop.

4. I had chosen to use CygWin on Windows for its Linux-flavored tasty 
goodness, and supplied Perl environment; strike two in a Windows-only 
shop.

5. Did I mention that that company was a Windows-only shop?

6. Ultimately, since comments are ignored by the language processor 
(compiler/interpreter), there is nothing to guarantee that the 
commentary has any lasting relationship to the code in which it is 
found.  Literate programming has attempted to provide code 
generation/execution directly from the descriptive documentation, but I 
do not recall anything in the 'mainstream' (not even LaTeX) that is 
available.

7. There are 'mind-mapper' tools and 'generic data-flow' graphing tools 
that generate both documentation and executable/interpretable code, 
presumably to allow Subject Matter Experts (SME) (who are not 
necessarily coding experts) to encapsulate their knowledge of a business 
process in a form that can be fed (along with data and triggering 
events) to an execution engine for emulation of the SME handling the 
data/trigger events.

and so on.  Thanks for reading.

=Aaron

--- news://freenews.netfront.net/ - complaints: news@netfront.net ---

[toc] | [prev] | [next] | [standalone]

#21470

On 2013-09-19 02:31, Stefan Weiss wrote:
> For those of you who write inline documentation blocks, what do you use
> to generate a user-readable API documentation from your source files?

Thanks to everybody who replied. It helped me with my decision (result:
keep using JSDoc for now). I escpecially appreciated the detailed report
about NaturalDocs (my condolences about the Windows shop thing), and I'm
looking forward to the improved doc generator announced by Thomas Lahn.

- stefan

[toc] | [prev] | [next] | [standalone]

#21472

On Wednesday, September 18, 2013 5:31:07 PM UTC-7, Stefan Weiss wrote:
> For those of you who write inline documentation blocks, what do you use
> 
> to generate a user-readable API documentation from your source files?
> 
> 
> 
Doc generators force comment clutter. The comments can and will fall out of sync when the code is refactored.

Comments should explain why, not what.

The code itself explains what it does. If it does not, then it needs to be refactored. 

I am pretty good at cleaning up code to make it so that I can read it. I like to walk others through the code to make sure that it is understandable, too. That way, they learn my style, I get a second pass over it, and they get a chance to spot errors.

* Separate files into patterns of reuse, to avoid cross-dependencies. 
* Name each file by what it does. FOr Objects and constructors, use proper camel and give the file the same name.
* Instead of "util" or "helper" -- describe the module by its usage pattern.
* Apply SRP to functions. 
* Use the narrowest scope needed. See also: http://www.velocityreviews.com/forums/t939478-where-should-variables-be-declared.html

See also: 
http://jibbering.com/faq/notes/code-guidelines/

README or wiki pages can be useful for high-level overview.

[toc] | [prev] | [next] | [standalone]

#21492

In comp.lang.javascript message <c3006ee2-3b46-4034-b9f9-40e078424410@go
oglegroups.com>, Mon, 30 Sep 2013 00:32:51, dhtml
<dhtmlkitchen@gmail.com> posted:

>Doc generators force comment clutter. The comments can and will fall
>out of sync when the code is refactored.

<FAQENTRY>

Referring to Version 32.2, Updated 2010-10-08, by Garrett Smith, section
1.3 : the first half of the fourth line of the third subsection should
be placed so that it applies also to the previous two subsection.

In fact, there should be a new leading subsection, on how to write an
article (i.e. applying to new questions & replies, and to plain text &
code).

The third like of the third subsection should be reconstructed, since it
is perfectly reasonable to ask why a particular piece of code appears
not to be executed.

</FAQENTRY>

-- 
 (c) John Stockton, nr London, UK.  Mail via homepage.  Turnpike v6.05  MIME.
  Web  <http://www.merlyn.demon.co.uk/> - FAQqish topics, acronyms and links.

[toc] | [prev] | [next] | [standalone]

#21496

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

[toc] | [prev] | [next] | [standalone]

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

[toc] | [prev] | [next] | [standalone]

#21498

On Wed, 02 Oct 2013 05:33:46 +0200, Stefan Weiss
<krewecherl@gmail.com> 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. 

That's my complaint. ...

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

... You don't remember to update the comment because you scrolled it
off the top of the screen before modifying the function.

  John

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.javascript

csiph-web