JSDuck

Create your own "Sencha" docs.

With Corey Butler / @goldglovecb

About Corey

  1. Cofounder, ThinkFirst, LLC
  2. Consultant @ Amazon, Atlassian, Discover Card, Constant Contact, ++
  3. Blog @ArtOfIdea.com
  4. github.com/coreybutler

About

Good For:

  1. Class-like code documentation.
  2. General guides (including user guides).

JSDuck - Built for Sencha

Welcome

Used By Sencha Component Developers (Bryntum)

Guides

Adapted By Others (Titanium)

Guides

Features

API

ArrayStore

Guides

Guides
Guides

Videos

Videos

Examples

Examples

Get It

gem install jsduck

or

github.com/senchalabs/jsduck

(jsduck.exe available for Windows)

How do I use it?

  1. Comment your code.
  2. Execute jsduck command line program.

Hello JSDuck


            /**
             * A duck, not just a stupid bird.
             */
            Duck = Ext.extend(Bird, {
              ...
            });
            
or

            /**
             * @class Duck
             * A duck, not just a stupid bird.
             * @extends Bird
             * @mixins Ext.util.Observable
             * @mixins Fliable
             * @singleton
             */
            Duck = Ext.extend(Bird, {
              ...
            });
            
@abstract
@accessor
@alias
@alternateClassName
@aside
@author
@cfg
@chainable
@class
@constructor
@deprecated
@docauthor
@enum
@event
@evented
@example
@extends
@ftype
@hide
@ignore
@inheritable
@inheritdoc
@markdown
@member
@method
@mixins
@new
@override
@param
@preventable
@private
@property
@protected
@ptype
@readonly
@removed
@requires
@return
@scss mixin
@since
@singleton
@static
@template
@throws
@type
@uses
@var
@xtype

My Own Tags?

@experimental
Document an experimental feature that may break.

@product @highlight @permissions

Customization

Custom Tags

Written in ruby.

require "jsduck/meta_tag"

module JsDuck::Tag
  # Implementation of @experimental tag
  class Experimental < JsDuck::MetaTag
    def initialize
      @name = "experimental"
      @key = :experimental
      @signature = {:long => "experimental", :short => "EXP"}
      @multiline = false
      @position = :top
    end

    def to_html(context)
      <<-EOHTML
        <p style='color:#ccc;border:2px dashed #eee;font-size:200%;border-radius:6px;'>
        This is an experimental feature that is not officially supported (yet).
        </p>
      EOHTML
    end
  end
end
  				  
Modified template for JSDuck 4.x

JSDuck 5 Syntax


require "jsduck/tag/boolean_tag"

class Inner < JsDuck::Tag::BooleanTag
  def initialize
    @pattern = "inner"
    @signature = {:long => "inner", :short => "in"}
    @html_position = POS_DOC + 0.1
    super
  end

  def to_html(context)
    "<p>This is an inner method, only accessible within the class itself.</p>"
  end
end
  				  

Cross References


Object.defineProperties(account,{

  /**
   * @cfg {String} user
   * The login assigned to a My.api.Login#person <-- References a different file
   */
  user: {
    value: config.user || 'unknown'
  },

  // Intentionally Ignored
  pwd: {
    enumerable: false,
    configurable: false,
    value: null
  },

  /**
   * @cfg {String} password
   * The password assigned to the #user  <-- references local configuration
   */
  password: {
    enumerable: false,
    get: function(){ return this.pwd.replace(/.*/gi,'*'); },
    set: function(value){ this.pwd = value; }
  }

});
            

Guides

# NGN Command Line

The NGN command line interface (CLI) automates some of the more tedious aspects
of creating and maintaining projects. The NGN CLI is available as an npm global
installation, i.e.

  npm install ngn -g

## Generate Class Stubs

Class stubs are a "fill in the blank" JavaScript class based on the NGN class system.
The CLI utility provides a wizard that will generate a working shell file. These files
should be filled in with the appropriate logic, but they will work natively with
developer-defined attributes.

To use the stub generator, execute the following command.

`ngn --create class`
  					

Written with Markdown.

Easy To Create

guides.json


[{
  "title": "Command Line Utilities",
  "items": [{
        "name": "cli",
        "title": "Wizards",
        "description": "Use NGN from the command line wizards..."
      }
   ]
},{
  ...
}
  				  

Customization++

Use CSS to Customize

Override CSS classes & make new ones

.console {
  -moz-border-radius: 20px;
  -webkit-border-radius: 20px;
  -khtml-border-radius: 20px;
  behavior: url(/assets/css/border-radius.htc);
  border-radius: 20px;
  position: relative;
  zoom: 1;
  background-color: #000000;
  color: #eeeeee;
  font-family: Monaco, Consolas, Arial, Helvetica, Sans-Serif;
  border: 1px solid #888888;
  border-top: 16px solid #888888;
}
  					
This file is included in the head-html configuration option:
<link rel="stylesheet" href="resources/css/custom.css" type="text/css">

Build It

Generating Docs


$ jsduck --builtin-classes --output my/docs project1/files/js project2/files/js
  					

$ jsduck --title="My personal docs" \
         --welcome="welcome.html" \
         --warnings=-link \
         --warnings=-no_doc \
         --seo \
         --html-head="<link rel='stylesheet' href='css/custom.css' type='text/css'>"
         src/Foo.js src/Bar.js src/Baz.js
  					

Use The Config


{
  "--title":    "NGN",
  "--welcome":  "assets/html/welcome.html",
  "--warnings": ["-link"],
  "--":       [],
  "--categories": "categories.json",
  "--guides":   "guides.json",
  "--html-head": "<link rel='stylesheet' href='css/custom.css' type='text/css'>",
  "--output":   "../manual"
}
  				  
$ jsduck --config=myconfig.json

Get GruntJS

  1. Install Node.JS.
  2. npm install -g grunt
  3. npm install grunt-jsduck
  4. npm install grunt-contrib-clean grunt-contrib-copy (Optional, but recommended)

jsduck: {
  main: {
    // source paths with your code
    src: [
      '../ngn/lib',
      '../ngn-idk/lib/core',
      './src/node/node'
    ],

    // docs output dir
    dest: './manual',

    // extra options
    options: {
      'title': 'NGN v'+cfg.ngn.version,
      'welcome': 'src/assets/html/welcome.html',
      'head-html': '',
      'categories': 'src/categories.json',
      'guides': 'src/guides.json',
      'meta-tags': 'custom/tags',
      'color': true,
      'builtin-classes': true,
      'comments-url':'http://comments.nodengn.com:81/auth',
      'comments-domain':'ngn/0.0.8',
      'warnings': ['-req_after_opt'],
      'external': ['XMLHttpRequest']
    }
  }
}
            

clean: {
  docs: ["./manual"],
},
copy: {
  jsduckassets: {
    files: [
      {expand: true, cwd: './src/css/', src:['*.*'], dest: './out/css/'},
      {expand: true, cwd: './src/images/', src:['*.*'], dest: './out/images/'}//,
    ]
  }
}
...
grunt.registerTask('default', ['clean:docs','jsduck','copy:jsduckassets']);
            

Can JSDuck doc:

Java? PHP? NodeJS?

Yup.

Even ColdFusion

Sneak Peak: NGN

Real Life JSDuck for Node.JS

Where JSDuck Helps

  • Infrastructure Development Kit (IDK) - API
  • Software Development Kit (SDK) - API
  • Services - Guides
  • Developer Tools - Guides
  • Getting Started - Examples/Videos
  • Required Customizations

    1. Basic Branding
    2. Welcome Page
    3. Tags (@process, @experimental)
    4. Node Icons
    5. CSS for Guides
    NGN Example Docs

    Questions?