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

Groups > comp.lang.javascript > #21394

Re: JS documentation generators

Show all headers | View raw

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

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