docjs 0.1.4 → 0.1.5

data/README.md

@@ -4,81 +4,51 @@ 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.
+
+Guides
+======
+If you read this, you may belong to one of the following four 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** is supported. I am working on supporting > 1.8.7, though this is not 
-my target platform.
+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.
 
 
 Installation
 ============
     gem install docjs    
 
-
-Required Gems
-=============
+Dependencies
+============
 The following Gems are required to make docjs work and should automatically be 
 installed while installing docjs:
 
-  - thor
-  - rdiscount
-  
-
-Basic Usage
-===========
-
-Configuration
--------------
-Before you can use Doc.js you may create your own **Configuration-File**. This 
-can easily be done, using the built-in 
-configuration-generator:
-
-    docjs configure
-    
-You optionally can specify the filename of your configuration file. If no file 
-is specified the configs will be written to `build.yml`.
-
-    docjs configure my_config_file.yml
+- thor
+- rdiscount
 
-The configuration is an interactive one - simply answer the questions you will 
-be asked.
 
-
-Start documenting your code
----------------------------
-To make jsdoc recognize your documentation you have to use some special tokens.
-Let's write a documented function `hello_doc`:
-    
-    /**
-     * @function hello_doc
-     *
-     * Innovative function to greet a Person.
-     *
-     * @param [String] name the person you want to greet
-     * @return void
-     */
-    function hello_doc(name) {
-      console.log("Hello " + name + "!");
-    }
-    
-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
-  
-
-Run the documentation and enjoy!
---------------------------------
-Now it's time to kickoff the documentation-process by typing:
-
-    docjs your_config.yml
-
-You will find the docs in the output-directory you have specified in your 
-config-file.
-
-
-Legal Notice
-============
+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 used icons, are part of the legendary [famfamfam-silk-iconset](http://www.famfamfam.com/lab/icons/silk/).
+
+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/bin/docjs

@@ -25,15 +25,37 @@ Configs.set :root  => Pathname.new(__FILE__).realpath + '../..'
 #
 # @note options declared in a docjs.yml will override command-line ones
 class DocJs < Thor
-    
+  
   include Thor::Actions
+  
+  def help(task = nil)
+  
+    # Introduction
+    unless task
+      say "Welcome to Doc.js", :bold
+      say "If you are using Doc.js for the first time in your project, you may want to create a config file (like docjs.yml)
+A guided wizard can help you achieving this goal - Simply run the following command:
+    docjs configure
+\n
+After creating a config-file (like docjs.yml) the documentation can be generated by running:
+    docjs docjs.yml
+
+For further information, please visit http://b-studios.github.com/doc.js\n\n"
+
+      self.class.help(shell, false)
+      
+    # Help for a specific task
+    else
+      self.class.task_help(shell, task)    
+    end
+  end
     
   desc "CONFIG_FILE", "Starts documentation process"
   set_options :files =>
-                  { :type => :array,  :aliases => '-f', :default => [], :required => true },
+                  { :type => :array,  :aliases => '-f', :default => [] },
                
               :docs =>
-                  { :type => :array,  :aliases => '-d', :default => ['README.md'], :required => true },
+                  { :type => :array,  :aliases => '-d', :default => ['README.md'] },
   
               :output =>
                   { :type => :string, :aliases => '-o', :default => 'out' },
@@ -209,16 +231,16 @@ class DocJs < Thor
   
   
   
-  desc "tasks TEMPLATE_PATH?", "Lists all registered render-tasks\nNeeds your TEMPLATE_PATH to include your own custom tokens. If TEMPLATE_PATH is ommitted, only the default-tokens will be shown"
-  def tasks(template_path = nil)
+  desc "generators TEMPLATE_PATH?", "Lists all registered generators\nNeeds your TEMPLATE_PATH to include your own generators."
+  def generators(template_path = nil)
     
     load_templates template_path
     
-    say "Registered render-tasks:"
+    say "Registered Generators:"
     
-    task_table = Tasks::RenderTask.all.map{|task| ["#{task.name}","# #{task.description}"] }.sort
+    gen_table = Generator::Generator.all.map{|gen| ["#{gen.name}","# #{gen.description}"] }.sort
     
-    print_table task_table, :ident => 2, :colwidth => 20    
+    print_table gen_table, :ident => 2, :colwidth => 40    
   end 
 end
 

data/bin/docjs.rb

@@ -25,15 +25,37 @@ Configs.set :root  => Pathname.new(__FILE__).realpath + '../..'
 #
 # @note options declared in a docjs.yml will override command-line ones
 class DocJs < Thor
-    
+  
   include Thor::Actions
+  
+  def help(task = nil)
+  
+    # Introduction
+    unless task
+      say "Welcome to Doc.js", :bold
+      say "If you are using Doc.js for the first time in your project, you may want to create a config file (like docjs.yml)
+A guided wizard can help you achieving this goal - Simply run the following command:
+    docjs configure
+\n
+After creating a config-file (like docjs.yml) the documentation can be generated by running:
+    docjs docjs.yml
+
+For further information, please visit http://b-studios.github.com/doc.js\n\n"
+
+      self.class.help(shell, false)
+      
+    # Help for a specific task
+    else
+      self.class.task_help(shell, task)    
+    end
+  end
     
   desc "CONFIG_FILE", "Starts documentation process"
   set_options :files =>
-                  { :type => :array,  :aliases => '-f', :default => [], :required => true },
+                  { :type => :array,  :aliases => '-f', :default => [] },
                
               :docs =>
-                  { :type => :array,  :aliases => '-d', :default => ['README.md'], :required => true },
+                  { :type => :array,  :aliases => '-d', :default => ['README.md'] },
   
               :output =>
                   { :type => :string, :aliases => '-o', :default => 'out' },
@@ -209,16 +231,16 @@ class DocJs < Thor
   
   
   
-  desc "tasks TEMPLATE_PATH?", "Lists all registered render-tasks\nNeeds your TEMPLATE_PATH to include your own custom tokens. If TEMPLATE_PATH is ommitted, only the default-tokens will be shown"
-  def tasks(template_path = nil)
+  desc "generators TEMPLATE_PATH?", "Lists all registered generators\nNeeds your TEMPLATE_PATH to include your own generators."
+  def generators(template_path = nil)
     
     load_templates template_path
     
-    say "Registered render-tasks:"
+    say "Registered Generators:"
     
-    task_table = Tasks::RenderTask.all.map{|task| ["#{task.name}","# #{task.description}"] }.sort
+    gen_table = Generator::Generator.all.map{|gen| ["#{gen.name}","# #{gen.description}"] }.sort
     
-    print_table task_table, :ident => 2, :colwidth => 20    
+    print_table gen_table, :ident => 2, :colwidth => 40    
   end 
 end
 

data/docjs.gemspec

@@ -4,8 +4,8 @@ Gem::Specification.new do |s|
 
 
   s.name = 'docjs'
-  s.version = '0.1.4'
-  s.date = '2011-06-17'
+  s.version = '0.1.5'
+  s.date = '2011-06-25'
   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.homepage = "https://github.com/b-studios/doc.js"

data/{DOCUMENTATION.md → docs/DOCUMENTATION.md}

@@ -3,9 +3,8 @@ Fullqualifier
 Like an absolute path (/etc/init.d/apache2) we use `FOO.bar` as fullqualifier to
 an object or function.
 
-A leading dot suggests filling the empty leading space with the current parsing-context
-without modifying it. As such `.something_else` would be resolved to 
-`FOO.bar.something_else` in the current context.
+A leading dot suggests filling the empty leading space with the current parsing-context. 
+As such `.something_else` would be resolved to `FOO.bar.something_else` in the current context.
 
 Examplecode:
 
@@ -38,4 +37,3 @@ Examplecode:
         property_of_the: "returned object"
       };    
     }
-

data/docs/PATTERNS.md

@@ -0,0 +1,101 @@
+Documentation Patterns
+======================
+There are some widely used patterns in JavaScript that need a proper way of documentation.
+
+Prototypal Inheritance
+----------------------
+Because most of the times (this is my personal impression) prototypal inheritence is used like in 
+the following example, Doc.js is specialized for that kind of prototyping.
+
+    /**
+     * @constructor Person
+     * This is the constructor for a Person. Just like you and me.
+     *
+     * @param [String] name The name of the person
+     * @param [Number] age
+     */
+    function Person(name, age) {
+      this.name = name;
+      this.age = age;
+    }
+
+    /**
+     * @prototype Person
+     */
+    Person.prototype = {
+
+      /**
+       * @object .configs
+       * @prop [Boolean] friendly
+       */
+      configs: {
+        friendly: true
+      },
+      
+      /**
+       * @method .sayHello
+       */
+      sayHello: function() {
+        if(this.friendly)
+          console.log("Hello " + this.name);
+          
+        else console.log("Grmppfbra!");
+      }
+
+    }
+
+Of course the usage of prototypes can easiliy be modified. For example to use prototype as a
+property like
+
+    /**
+     * @constructor Collection
+     * @prototype Array.prototype
+     */
+    function() {
+      ...
+    }
+
+you have to delete the CodeObject::Prototype in `types/prototype.rb` and then register a token like
+
+    register :prototype, :area => :none
+
+
+
+Revealing Module Pattern
+------------------------
+The Revealing Module Pattern is a way of declaring some properties of an object as **private** and 
+reveal only the public ones. This can be documented like the following:
+
+     /**
+      * @constructor Person
+      * @param [String] name
+      */
+      function Person(name) {
+      
+      
+        var methods = {
+        
+          /**
+           * @method .eatPizza
+           * @private
+           */
+          eatPizza: function() {
+            ...mhh...
+          }        
+        }
+      
+        return {
+        
+          /**
+           * @method .sayHello
+           * Outputs a cheerfull greeting, containing the person's name
+           */
+          sayHello: function() {
+            console.log("Hello, from " + name)
+          }        
+        };
+     
+      }
+      
+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

@@ -0,0 +1,158 @@
+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.
+Let's say we want to add a new innovative token `@requires` to specify dependencies to other objects.
+
+    /**
+     * @function say_hello
+     * @requires console.log
+     */
+
+If we start Doc.js without making any changes to the templates this documentation will result in an 
+error like **ERROR No Tokenhandler for: @requires**. 
+So let's register our tokenhandler to `tokens/tokens.rb`:
+
+    register :requires
+  
+  
+Changing the area
+-----------------  
+The token will now be processed using the {Token::Handler :text_only} tokenhandler and will appear
+in the `:body` section of the template. Because `requires` may fit much better in the `:sidebar` 
+section (it contains meta-information about the object) we place it there with
+
+    register :requires, :area => :sidebar
+    
+Now our token should be displayed nicely in the sidebar-area on the right side (if you are using the
+default template).
+
+
+Using another tokenhandler
+--------------------------
+While using our new token, we may notice, that it would be nice if we can specify some detailed
+information about the dependency like:
+
+    /**
+     * @function say_hello
+     * @requires console.log for printing the message to the console
+     */
+
+So we have to change the tokenhandler to `:named` because our tokenline now consists of a `name`
+and the description-`content`.
+
+    register :requires, :area => :sidebar, :handler => :named
+    
+The template, which renders the token now can access the `name` and the `content` of the token 
+seperatly and displays them somehow like:
+
+    <h4>console.log</h4>
+    <p>for printing the message to the console</p>
+
+
+Creating a custom template
+--------------------------
+We've come pretty far with just adding one line to our own templates. But now we want to use our own
+template for this token, because the title isn't automatically linked, if the required object exists
+in our documentation. Because this would be a cool features, let's implement it.
+
+First of all we have to create our partial. Like all other templates, the token-partials are located 
+under `views/tokens`. So we create a file called `views/tokens/_requires.html.erb` and fill in some
+content:
+
+    <section>
+      <h3>Dependencies</h3>
+      <ul>
+        <% tokens.each do |token| %> 
+          <li>
+            <h4><%=link_to token.name %></h4>
+            <%=to_html token.content %>
+          </li>
+        <% end %>
+      </ul>
+    </section>
+    
+Because all tokens of one type are rendered as a collection by default, we have to iterate over our
+local-variable `tokens`. We use the {Helper::Linker#link_to link_to} helper to create a link to the
+referenced dependency if it exists in our documentation. Additionally we use the 
+{Helper::Helper#to_html to_html} helper to convert the description (which could be written using
+markdown and contain links we need to generate) to html.
+
+Last thing we have to do, is to make the renderer use our new template for `@requires` tokens
+
+    register :requires, :area => :sidebar, :handler => :named, :template => :requires
+
+
+2. Example - Writing your own token-handler
+===========================================
+There are a {Token::Handler few handlers}, which can be used to process the tokenlines. But sometimes
+one of the existing handlers isn't enough to process your token.
+
+Let's say we need a tokenhandler to parse something like
+
+    /**
+     * @special [String] my_name (default) description
+     */
+
+We could get pretty close using the :typed_with_name handler. But this handler doesn't recognizes
+defaults, so we need to write our own handler.
+
+First of all we register our token in `tokens/tokens.rb`.
+
+    register :special do |tokenklass, content|
+      # currently the textual content is only stored as `content`
+      self.add_token token_klass.new(:content => stringcontent)
+    end
+    
+Next let's write a Regexp, that recognizes our parts. (Ok, that regular expression may not be the
+most beautiful one, but it may work)
+    
+    register :special do |token_klass, content|
+    
+      TYPED_NAMED_WITH_DEFAULTS = /\[([^\]\n]+)\]\s*([\w_.:]+)\s(?:\(([^\)]+)\))?\s*(.*)/
+      
+      types, name, default, content = TYPED_NAMED_WITH_DEFAULTS.match(content).captures
+      token = token_klass.new(:name => name, :types => types.split(','), :content => content)
+      token.define_singleton_method(:default) { default }
+      
+      self.add_token token
+    end
+    
+Because :default isn't a default property of token, we have to add it manually by defining a
+method which returns the value (`define_singleton_method`).
+
+The last thing, we would have to do is to create a custom template and use it. See 
+{file:CUSTOMIZE.md#Creating_a_custom_template above} for tipps how to achieve this.
+The template could make use of `token.default` to access the default value parsed by our cool
+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`. 
+