docjs 0.1.5 → 0.2

data/LICENSE.md

@@ -1,19 +1,16 @@
 Copyright (C) 2011 by Jonathan Brachthäuser (http://b-studios.de)
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
+associated documentation files (the "Software"), to deal in the Software without restriction, 
+including without limitation the rights to use, copy, modify, merge, publish, distribute, 
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all copies or substantial 
+portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT 
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES 
+OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -4,51 +4,60 @@ Bad news first: **You still have to write documentation**
 
 Good news: **It will look awesome!!**
 
-Doc.js is a JavaScript-Documentation tool which detects `tokens` in your comments and 
-generates documentation out of it. Doc.js could be ported pretty easy to any other
-language, because the most of it's parts are language agnostic.
+Doc.js is a JavaScript-Documentation tool which detects `tokens` in your comments and generates 
+documentation out of it. Doc.js could be ported pretty easy to any other language, because the most 
+of it's parts are language agnostic.
+
+Features
+--------
+- One command to install
+- Use markdown in your documentation
+- Easy to customize (Create your own DSL in a sec!)
+- Nice and clean default template
+- Integrates well with your existing deployment
+- For ruby lovers - it's written in ruby
 
 Guides
-======
-If you read this, you may belong to one of the following four groups:
+------
+If you read this, you may belong to one of the following groups:
 
 1. You want to {file:TRY.md try out Doc.js} for the first time
 2. You need some more {file:USE.md information, how to use Doc.js}
 3. You want to {file:CUSTOMIZE.md customize Doc.js}, to exactly fit your needs
-4. You are interested in the {file:ARCHITECTURE.md architectural insides} of Doc.js
 
 Supported Ruby-Version
-======================
-Currently **only ruby > 1.9.x is supported**. Support for 1.8.x is not planned, 
-because there are some problems:
+----------------------
+Currently **only ruby > 1.9.x is supported**. Support for 1.8.x is not planned, because there are 
+some problems:
 
 - UTF-8 Support in parser
 - Intensive use of require_relative
 - Named captures in RegularExpressions
 
-For the last two, a rewrite could solve the compatibility issues. Sadly enough
-currently i don't find the time to fix thoses and the first problem in 1.8.x so
-only 1.9 is supported. If you have the time to work on 1.8 compatibility you would
-make me (and possibly some other 1.8 users) very happy.
+For the last two, a rewrite could solve the compatibility issues. Sadly enough currently i don't 
+find the time to fix thoses and the first problem in 1.8.x so only 1.9+ is supported. If you have 
+the time to work on 1.8 compatibility you would make me (and possibly some other 1.8 users) very 
+happy.
 
 
 Installation
-============
+------------
     gem install docjs    
 
 Dependencies
-============
-The following Gems are required to make docjs work and should automatically be 
-installed while installing docjs:
+------------
+The following Gems are required to make docjs work and should automatically be installed while 
+installing docjs:
 
 - thor
 - rdiscount
 
 
 Legal Notice & Contact
-======================
+----------------------
 docjs is released under MIT-License. See LICENSE.md for more information.
 The used icons, are part of the legendary [famfamfam-silk-iconset](http://www.famfamfam.com/lab/icons/silk/).
+The font used in title and headlines is a Google-Webfont called `TerminalDosis-Light`.
 
 For further information about contacting me, please visit my personal [blog](http://b-studios.de).
 Of course you are also invited to [follow me on twitter](http://twitter.com/#!/__protected).

data/docjs.gemspec

@@ -4,10 +4,10 @@ Gem::Specification.new do |s|
 
 
   s.name = 'docjs'
-  s.version = '0.1.5'
-  s.date = '2011-06-25'
+  s.version = '0.2'
+  s.date = '2011-06-28'
   s.summary = "Javascript Documentation Generator"
-  s.description = "Create beautyful Javascript documentations with this ruby-gem. It's pretty easy to customize and add your own tokens/DSL."
+  s.description = "Create beautiful Javascript documentations with this ruby-gem. It's pretty easy to customize and add your own tokens/DSL."
   s.homepage = "https://github.com/b-studios/doc.js"
   s.authors = ["Jonathan Brachthäuser"]
   s.email = "jonathan@b-studios.de"

data/docs/PATTERNS.md

@@ -97,5 +97,5 @@ reveal only the public ones. This can be documented like the following:
      
       }
       
-Ommiting the comment of the private function `eatPizza` would exclude it from the documentation. This
-may be the disired way of documenting for example a API-Documentation.
+Ommiting the comment of the private function `eatPizza` would exclude it from the documentation. 
+This may be the disired way of documenting for example a API-Documentation.

data/docs/guides/CUSTOMIZE.md

@@ -1,27 +1,3 @@
-Areas
-=====
-To visually group the tokens you can specify an area. All tokens for one area (`:sidebar` in this
-example) will be collected and can be rendered in the view-templates with the 
-{Helper::Helper#render_tokens render_tokens} helper-method. 
-
-    render_tokens :of => @code_object, :in => :sidebar
-
-While {Token::Handler.register registering a new token} you can use any symbol for `area`. But your tokens may not appear in 
-the rendered html-documentation, unless you explicitly call `render_tokens` for each area.
-
-The default-templates make use of the following areas:
-
-- :notification
-- :body
-- :sidebar
-- :footnote
-
-If you don't want your token to be rendered at all, you can use `:none` as value for `area`.
-
-    register :your_token, :area => :none
-
-
-
 1. Example - Adding a simple token
 ==================================
 You can extend Doc.js on different levels. The easiest way of customization is to add a simple token.
@@ -50,6 +26,8 @@ section (it contains meta-information about the object) we place it there with
 Now our token should be displayed nicely in the sidebar-area on the right side (if you are using the
 default template).
 
+You can find more information about areas in {Helper::Helper#render_tokens the Helper-doc}
+
 
 Using another tokenhandler
 --------------------------
@@ -151,8 +129,127 @@ token-handler.
 
 3. Example - Creating the custom type `class`
 =============================================
-If you want to create your own Domain specific language (DSL) it's often not enough to add new tokens
-and manipulate the templates. Sometimes you need to create your own custom types of objects. For 
-example maybe you could need classes, packages or mixins. So in this example we will create a type
-called `class`. 
+If you want to create your own Domain specific language (DSL) it's often not enough to add new 
+tokens and manipulate the templates. Sometimes you need to create your own custom types of objects. 
+For example maybe you could need classes, packages or mixins. So in this example we will create a 
+type called `class`. 
+
+The template-folder `types/` contains 3 items by default:
+
+    types/
+      function.rb
+      object.rb
+      prototype.rb
+
+We will create a fourth one and call it `class.rb`, which at first only consists of 
+
+    class CodeObject::Class < CodeObject::Base
+    end
+    
+Then we need to `require` it from `application.rb`
+
+    require_relative 'types/class.rb'
+    
+We get serious problems here, because in ruby we cannot redefine `Class` without getting into 
+troubles. With nearly all other Type-Names everything wents fine, but for `Class` we need something 
+different. Maybe we can simply call it `Klass` or `ClassType` to bypass any trouble. It's up to you.
+
+    class CodeObject::Klass < CodeObject::Base
+    end
+
+Based on the name you choosed, we now have to register our token, to be a Type-Creating Token.
+Every Comment needs exactly one of these type-specificating tokens. With the following line (either
+in `tokens.rb` or in `class.rb`, after defining our type) we make our token work:
+
+    Token::Handler.register :class, :type => CodeObject::Klass
+    
+Using `@class` in a comment will create an instance of CodeObject::Klass and fill it with all 
+details of that comment.
+
+If we don't want our type-token to appear in any token-listing like :body or :sidebar we can 
+specify :none for the rendering-area.
+
+    Token::Handler.register :class, :type => CodeObject::Klass, :area => :none
+
+If we test our customized template with something like
+
+    /** 
+     * @class Collection
+     */
+    var Collection = function() { ... };
+    Collection.prototype = Array.prototype;
+    
+we may notice, that nothing is really different from using `@object` instead. That's only because
+our template is not yet specialised to work with classes.
+
+Modifying a Generator
+---------------------
+We learned how to create our own templates. But now we need to switch between different templates
+before rendering starts. To understand where rendering starts, we need to inspect the generators.
+{Generator::Generator Generators} in Doc.js are pretty much like `Controllers` in Rails. They
+decide which template to use and where to save the result. So let's take a look at the
+{Generator::ApiPagesGenerator generators/api_pages_generator.rb}. We can see that every generator
+is able to choose which layout it want's to render the pages in.
+
+We may notice, that the ApiPagesGenerator is nothing more than a switch for CodeObject-Types. By
+default it only differs between {CodeObject::Function functions} and those, that are not functions.
+
+We can add some code, to use own templates for classes.
+
+    Dom.root.each_child do |node| 
+      next if node.is_a? Dom::NoDoc 
+        
+      if node.is_a? CodeObject::Function
+        render_function node
+      elsif node.is_a? CodeObject::Klass
+        render_class node
+      else
+        render_object node
+      end
+    end
+
+We invoke a method, which is not yet defined '`render_class`'. This method get's the node as the
+only parameter and needs to create html-output from it.
+
+    def render_class(code_object)       
+    
+      Logger.info "Rendering Class: '#{code_object.name}'"
+      
+      # This is needed to eventually resolve relative links included in the documentation
+      in_context code_object do
+        
+        # The instance-variables are also available in the template-views
+        @class = code_object
+        @methods = @object.children.values.select {|c| c.is_a? CodeObject::Function }
+        
+        # Here we call our new template, stored under `views/class/index.html.erb`
+        render 'class/index', :to_file => path_to(code_object, :format => :html)
+      end
+    end
+    
+The last thing (and granted, this may be the biggest part) is to create a template, which is 
+optimzed regarding our new type `class`.
 
+Combination with a custom handler
+---------------------------------
+Often classes are used in context of the classical inheritance. Once class extends another.
+So we may add a new token `@extends`, which is a text-only token-handler, maybe with a custom 
+template. (See first example above)
+
+It would be much more interesting to add a documentation syntax like:
+
+    /**
+     * @class Student < Person
+     */
+     
+This is way easiert, than it may look like at first glance. We only have to write a custom handler:
+
+    Token::Handler.register :class, :type => CodeObject::Klass, :area => :none do |tokenklass, content|
+      extends = /\s*[^\s]+\s*(?:<\s*([^\s]+))/.match(content)
+      
+      self.add_token Token::Token::ExtendsToken.new(:content => extends.captures.first) unless extends.nil?
+    end
+    
+What is this doing? We first match our token-content against a regular expression like `(Word (< Word)?)`
+the inner word is captured. If this matches we use the second part (after the `<`) to create an 
+`@extends` token.

data/docs/guides/TRY.md

@@ -51,7 +51,8 @@ The symbols `@function`, `@param` and `@return` are called **tokens** in Doc.js.
 There are many more by default. To see which one you can use simply type:
 
     docjs tokens
-  
+
+or simply search in {file:USE.md#Available_Tokens this list}.
 
 Run the documentation and enjoy!
 --------------------------------

data/docs/guides/USE.md

@@ -64,11 +64,9 @@ default:
 - `@prototype`
 - (`@constructor`)
 
-The first two are considered primitives of the JavaScript language. Advanced concepts like classes, 
-mixins, pseudoclassical inheritence and so on can easily be added by 
-{file:CUSTOMIZE.md creating your own template} or modifying the existing one. `@prototype` is added
-as type, so you can see how to create your own custom-types. More information about the `@prototype`
-- type can be found in {file:PATTERNS.md#Prototypal_Inheritance the documentation-pattern-list}.
+Advanced concepts like classes, mixins, pseudoclassical inheritence and so on can easily be added by 
+{file:CUSTOMIZE.md creating your own template} or modifying the existing one. More information about 
+the `@prototype`-type can be found in {file:PATTERNS.md#Prototypal_Inheritance the documentation-pattern-list}.
 
 Types classify the piece of code, you are documenting - so adding a type is essential and **always 
 required**.
@@ -111,7 +109,7 @@ can be rewritten as:
 This only works, because the JavaScript-Parser of Doc.js is working scope-aware. So you always can 
 use the dot-notation if your comment is in the lexical-scope of the parent comment.
 
-The dot-notation (`.sayHello`) was inspired by file-system, where one dot refers to the current
+The dot-notation (`.sayHello`) was inspired by file-systems, where one dot refers to the current
 directory. It also fit's into the JavaScript context, because the child can be accessed by using
 the dot.
 
@@ -120,67 +118,92 @@ Please note: **If relative naming results in errors you still can use absolute n
 Available Tokens
 ================
 
-@author
--------
+
+Meta-Information Tokens
+-----------------------
 | Handler          | Area       | Template
 |:-----------------|:-----------|:-------------
 | :default         | :sidebar   | :default
 
-Can be used multiple times for many authors like:
-
-    @author Jon Foo
-    @author Peter Bar (Editor)
-    
+All meta-information tokens appear, along hierachy and file-information, in the sidebar on the right
+side. (That area is called `:sidebar`)
+All contents is parsed as one string and can be accessed via the content-accessor-method:
 
-@constructor
-------------
-Simply creates a function-type and makes it answer `fun.constructor?` with `true`.
+    code_object.tokens[:author].first.content #=> Jonathan
 
+### @author #
+### @public #
+### @private #
+### @version #
 
-@deprecated 
------------
-| Handler          | Area           | Template
-|:-----------------|:---------------|:-------------
-| :default         | :notification  | :default
 
-@event
-------
-| Handler                  | Area    | Template
-|:-------------------------|:--------|:-------------
-| :named_nested_shorthand  | :body   | :default
+Notification Tokens
+-------------------
+| Handler          | Area          | Template
+|:-----------------|:--------------|:-------------
+| :default         | :notification | :default
+The notification tokens are all rendered within the default-template, but can be distinguished with
+css, because the token is added as class.
 
-@example
---------
-| Handler          | Area   | Template
-|:-----------------|:-------|:-------------
-| :named_multiline | :body  | :example
-
-@function
----------
-Type
+    /**
+     * @warn This is a warning
+     * @note Please note this
+     */
+     
+will result in a markup similar to:
+
+    <section class="warn subsection">
+      <h3>Warn</h3>
+      <ul>
+        <li><p>This is a warning</p></li>  
+      </ul>
+    </section>
+    <section class="note subsection">
+      <h3>Note</h3>
+      <ul>
+        <li><p>Please note this</p></li>  
+      </ul>
+    </section>
+
+### @deprecated #
+### @note #
+### @todo #
+### @warn #
+
+
+Type-Creating Tokens
+--------------------
+| Handler          | Area  | Template
+|:-----------------|:------|:-------------
+| :noop            | :none | :default
+
+Using type-tokens like `@object` set's the type of the documented CodeObject to {CodeObject::Object}
+in this case. No token will be added to the codeobject, because the token-types are registered with
+:noop as token-handler. See {file:USE.md#Types types} for further information about the types in Doc.js.
+
+All type-tokens take the first word as path of the described object:
 
+    /**
+     * @function Core.extend
+     */
 
-@method
--------
-Type
+`@function Core.extend` describes the function `extend` in the namespace `Core`.
+### @constructor #
+Simply creates a function-type and makes it answer `fun.constructor?` with `true`.
 
-@note
------
-| Handler          | Area           | Template
-|:-----------------|:---------------|:-------------
-| :default         | :notification  | :default
+### @function #
+### @method #
+### @object #
+### @prototype #
 
-@object
--------
-Using @object set's the type of the documented CodeObject to {CodeObject::Object}. No token will be
-added. See {file:USE.md#Types types} for further information about the types in Doc.js.
 
-@overload
----------
-| Handler      | Area   | Template
-|:-------------|:-------|:----------
-| :custom      | :none  | :default
+Function-Specific Tokens
+-----------------------
+Of course there are the Function-{file:USE.md#Type-Creating_Tokens Type creating tokens} like 
+`@constructor`, `@function` and  `@method`. But there are some more tokens, which are designed to
+work with functions.
 
+### @overload #
 You can use overloads, if your **function requires multiple signatures**.
 So instead of adding your `@param`'s and `@return`'s directly to the function's documentation you 
 specify overloads like:
@@ -206,51 +229,78 @@ specify overloads like:
 Please note, that in line 7 of this example the continuation of @overload is achieved due intending
 the empty line with some spaces.
 
+### @param #
+The @param-token supports two ways of usage. The first one is for default tokens like:
+
+    /**
+     * @param [Foo] barname some description
+     */
 
-@param
-------
+The second one you can use to describe config-objects, which can be passed as an parameter  
 
-@private
---------
-| Handler          | Area       | Template
-|:-----------------|:-----------|:-------------
-| :default         | :sidebar   | :default
+    /**
+     * @param configs
+     * Some configuration Object with following properties:
+     * [String] foo some string
+     * [Bar] bar and another one
+     */
+     
+### @return #
+### @throws #
 
-@prop
------
 
-@prototype
-----------
+Miscellaneous Tokens
+----------------------
+### @event #
+| Handler                  | Area    | Template
+|:-------------------------|:--------|:-------------
+| :named_nested_shorthand  | :body   | :default
 
-@public
--------
-| Handler          | Area       | Template
-|:-----------------|:-----------|:-------------
-| :default         | :sidebar   | :default
+Basically the event token was created to document which events an object could fire.
+Because events often contain data with them, there is the possibility to document the format of this
+data. (this is why the :named_nested_shorthand-handler is used)
 
-@return
--------
+    /**
+     * @event MyCustomEvent
+     *   This event will be triggered, if something special happens. The registered handler will be
+     *   called with a data-object
+     *   [Object] obj This object
+     *   [String] msg Some message attached to this event
+     */
+     
+### @example #
+| Handler          | Area   | Template
+|:-----------------|:-------|:-------------
+| :named_multiline | :body  | :example
 
-@see
-----
+Examples can be used with and without a title:
 
-@throws
--------
+    /**
+     * @example no parameters
+     *   person.say_hello();
+     *
+     * @example with parameters
+     *   person.say_hello({
+     *     be_friendly: true 
+     *   });
+     */
 
-@todo
------
-| Handler          | Area           | Template
-|:-----------------|:---------------|:-------------
-| :default         | :notification  | :default
 
-@version
---------
-| Handler          | Area       | Template
-|:-----------------|:-----------|:-------------
-| :default         | :sidebar   | :default
+### @prop #
+| Handler           | Area    | Template
+|:------------------|:--------|:-------------
+| :typed_with_name  | :body   | :default
+Prop-tokens are designed to be used to describe properties of objects, which are not objects 
+themselves.
 
-@warn
------
-| Handler          | Area           | Template
-|:-----------------|:---------------|:-------------
-| :default         | :notification  | :default
+    /**
+     * @object parameters
+     * @prop [String] foo
+     * @prop [Number] bar
+     */
+    var parameters = {
+      foo: "Hello World",
+      bar: 42      
+    }
+    
+### @see #