docjs 0.1.4 → 0.1.5

data/lib/processor.rb

@@ -1,6 +1,6 @@
 require 'rdiscount'
 require_relative 'dom/dom'
-require_relative 'tasks/render_task'
+require_relative 'generator/generator'
 require_relative 'document/document'
 
 module Processor
@@ -52,18 +52,9 @@ module Processor
   
   
   # @group Stage #3 - TemplateProcessor  
-  
-  # just some notes
-  
-  # command line:
-  #     $~ jsdoc render_tasks
-  #     Registered Rendertasks:
-  #     - typed:     renders objects type-dependant
-  #     - overview:  renders an overview
-  #     - files:     converts specified markdown files and renders them
-  #  
+
   def self.perform_all_tasks
-    Tasks::RenderTask.all.each { |task| task.new.perform }
+    Generator::Generator.all.each { |task| task.new.perform }
   end
   
   # @group Stage #4 - Document Processor

data/lib/renderer.rb

@@ -58,6 +58,8 @@ class Renderer
         # create directories recursive
         FileUtils.mkpath File.dirname opt[:to_file]
 
+        # Working with Thor-Actions would be nice, but it seems to be too much overhead for this small
+        # renderer
         File.open(opt[:to_file], "w+") do |f|
           f.write view
         end

data/lib/token/container.rb

@@ -52,7 +52,8 @@ module Token
     
       # try to find matching tokenklass for token i.e. Token::Token::ParamToken for :param
       begin
-        tokenklass = Token.const_get "#{tokenline.token.capitalize.to_s}Token"
+        camelcased = tokenline.token.to_s.capitalize.gsub(/_\w/){|w| w[1].capitalize}
+        tokenklass = Token.const_get "#{camelcased}Token"
         instance_exec(tokenklass, tokenline.content, &(tokenklass.handler))
       rescue Exception => error
         raise NoTokenHandler.new("No Tokenhandler for: @#{tokenline.token}

data/lib/token/handler.rb

@@ -1,10 +1,10 @@
 require_relative 'token'
 
-# This module contains all required mixins and modules to register customized
-# tokens, that will be further processed and added to the {CodeObject::Base}.
+# This module contains all required mixins and modules to register customized tokens, that will be 
+# further processed and added to the {CodeObject::Base}.
 #
-# The {CodeObject::Converter converter} starts the {Parser::Tokenline tokenline}-processing, by calling
-# the mixed-in function {Token::Container#process_token}.
+# The {CodeObject::Converter converter} starts the {Parser::Tokenline tokenline}-processing, by 
+# calling the mixed-in function {Token::Container#process_token}.
 #
 # ![Token UML](../uml/Tokens.svg)
 #
@@ -15,38 +15,149 @@ require_relative 'token'
 #       individual token-{Token::Container#add_token container} and 
 #       {Token::Container#process_token -processing} functionality to all CodeObjects.
 #
+# Tokenprocessing means analysing the tokenline (plain textual content associated with a token) by
+# applying a tokenhandler to it. The tokenhandler should parse the tokenline into it's contents and
+# afterwards create an instance of the token-class.
 module Token
 
   # @note This module is **not** built to be used as a mixin! It should be seen as
   #  a **global singleton** instead.
   # 
   # The {Token::Handler} is meant to be the global store for all Token-handlers.
-  # Token-handlers are needed to process incoming {Parser::Tokenline tokenlines}
-  # of each comment. The following sample, shows a comment including a token line:
+  # Token-handlers are needed to process all {Parser::Tokenline tokenlines} associated with
+  # each comment. The following sample, shows a comment including a token line:
   #
   #     /**
-  #      * @token this is a default tokenline
+  #      * @foo this is a default tokenline
   #      */
   #
-  # This Comment will be transformed by the {Parser::CommentParser} into a
+  # This comment will be transformed by the {Parser::CommentParser} into a
   # {Parser::Tokenline tokenline} like the following:
   #
   #     puts my_tokenline
-  #     #=> <struct Parser::Tokenline token="token", content="this is a default tokenline"> 
+  #     #=> <struct Parser::Tokenline token="foo", content="this is a default tokenline"> 
   #
-  # After creating the right type of {CodeObject::Base CodeObjects} (either a
-  # {CodeObject::Object Object} or {CodeObject::Object Function}) the 
-  # {CodeObject::Converter converter} will trigger the conversion to a 'real' 
-  # {Token::Handler::Token token} by calling {Token::Container#process_token #process_token}
+  # After creating the right type of {CodeObject::Base CodeObjects} (either an
+  # {CodeObject::Object Object}, {CodeObject::Object Function} or a custom type) the 
+  # {CodeObject::Converter converter} will trigger the conversion to an appropriate subclass of
+  # {Token::Token} by calling {Token::Container#process_token #process_token}
   # on the CodeObject.
   #
   #     code_object.process_token(my_tokenline)
   #     code_object.token(:token)
-  #     #=> [#<struct Token::Handler::Token content="this is a default tokenline">]
+  #     #=> [#<Token::FooToken content="this is a default tokenline">]
   #
-  # Tokens are always stored in an array to make multiple usage in one comment
-  # possible.
+  # Tokens are always stored in an array to make multiple usage in one comment possible.
+  # For example one function-comment can contain many `@param`s:
+  #    
+  #     /**
+  #      * @function foo
+  #      * @param [Number] bar
+  #      * @param [String] baz
+  #      */
+  #
+  # Default Handlers
+  # ================
+  # 
+  # :text_only
+  # ----------
+  # The default Header :text_only cannot parse typelists or tokennames, it
+  # only saves the content of the token to an instance of {Token::Token}
+  # Being the default handler we can use it without explicitly specifying it:
+  #
+  #      Token::Handler.register :token
+  # 
+  # This Default Handler is enough for tokens like `@todo` or `@note`. But for
+  # more complex Tokens we need some other handlers.
+  #
+  # :typed
+  # ------
+  # Typed tokens look like 
+  #
+  #     @return [Foo, Bar] This is the description
+  #
+  # Additional to their default **content** they specify the possible **types** as a commaseperated 
+  # list.
+  #  
+  # To register a typed-token, you only need to add the `:handler` option
+  #  
+  #     Token::Handler.register :return, :handler => :typed
+  #  
+  # This line implicitly generates a class `Token::ReturnToken` which extends {Token::Token},
+  # content and types will be filled to access them later:
   #
+  #     my_return_token.content #=> "This is the description"
+  #     my_return_token.types   #=> ["Foo", "Bar]
+  #
+  # :named
+  # ------
+  # Named tokenlines like
+  #
+  #     @mixin Foo.bar The description of this mixin-usage
+  #
+  # interpret the first part (`Foo.bar`) as **name** and the rest as **content**
+  #
+  #     Token::Handler.register :mixin, :handler => :named
+  #     
+  #     mixin_token.name    #=> "Foo.bar"
+  #     mixin_token.content #=> "The description of this mixin-usage"
+  #
+  # :named_multiline
+  # ----------------
+  # Named multiline are similiar to named tokenlines. But instead of taking the first word as
+  # name they are using the first line:
+  #
+  #     @example this is the name
+  #       function() {...}
+  #
+  # To register a named-multiline token just add the handler like:
+  # 
+  #     Token::Handler.register :example, :handler => :named_multiline
+  #
+  #     my_example.name    #=> "this is the name"
+  #     my_example.content #=> "function() {...}"
+  #
+  # :typed_with_name
+  # ----------------
+  # The typed_with_name handler is much like the **Typed-Token-Handler**. It is neccessary for
+  # tokenlines, like
+  #
+  #     @param [String] my_param This is a param
+  #
+  # Additional to **content** and **types** the generated class will contain a **name** property.
+  #
+  #     Token::Handler.register :param, :handler => :typed_with_name   
+  #     
+  #     param_token.name     #=> "my_param"
+  #     param_token.types    #=> ["String"]
+  #     param_token.content  #=> "This is a param"
+  #     param_token.class    #=> Token::ParamToken
+  #
+  # :named_nested_shorthand
+  # -----------------------
+  # named_nested_shorthand can be used to parse nested `:typed_with_name` tokens.
+  # 
+  #     @param person
+  #       [String] name the name
+  #       [Number] age the age of the person
+  #
+  # It is called shorthand, because "`[String] name the name`" is not a full tokenline. (The 
+  # `@param` is missing.)
+  #
+  #     Token::Handler.register :param, :handler => :named_nested_shorthand 
+  #
+  # The instance of `Token::ParamToken` can look like:
+  # 
+  #     param_token.name     #=> "person"
+  #     param_token.children # [<Token::ParamToken name="name"><Token::ParamToken name="age">]
+  #
+  # It also can parse typed_with_name tokenlines like `@param [String] name`. In this case it
+  # behaves exaclty like :typed_with_name
+  #
+  # :noop
+  # ----- 
+  # Can be used, if you don't want to do anything with that token
+  # 
   # @see .register
   module Handler
   
@@ -55,6 +166,9 @@ module Token
     IDENTIFIER = /(?:[^\s])*/
     TYPELIST = /\[(?<types>#{IDENTIFIER}(?:,#{NO_BR}*#{IDENTIFIER})*)\]/
     
+    # Tokens with name and content
+    NAME = /#{NO_BR}*(?<name>#{IDENTIFIER})#{NO_BR}*(?<content>#{ALL}*)/
+    
     # Token with type and content
     TOKEN_W_TYPE = /#{NO_BR}*#{TYPELIST}#{NO_BR}*(?<content>#{ALL}*)/
     
@@ -66,9 +180,8 @@ module Token
       (?<content>#{ALL}*)
     /x
     
-    
-    # @note It would be nice, if those defaults could be used without self.add_token
     @@defaults = {
+
       :text_only => ->(tokenklass, content) {
         tokenklass.new(:content => content)
       },
@@ -79,14 +192,12 @@ module Token
         
         tokenklass.new(:types => types, :content => content)
       },
-
-      :typed_with_name => ->(tokenklass, content) {
-        typestring, name, content = TOKEN_W_TYPE_NAME.match(content).captures
-        types = typestring.split /,\s*/
-        
-        tokenklass.new(:name => name, :types => types, :content => content)
-      },
       
+      :named => ->(tokenklass, content) {
+        name, content = NAME.match(content).captures        
+        tokenklass.new(:name => name, :content => content)
+      },
+       
       :named_multiline => ->(tokenklass, content) { 
         rows = content.split(/\n/)
               
@@ -96,10 +207,17 @@ module Token
               
         tokenklass.new(:name => name, :content => content)
       },
+
+      :typed_with_name => ->(tokenklass, content) {
+        typestring, name, content = TOKEN_W_TYPE_NAME.match(content).captures
+        types = typestring.split /,\s*/
+        
+        tokenklass.new(:name => name, :types => types, :content => content)
+      },
       
       :named_nested_shorthand => ->(tokenklass, content) {
           
-        # First remove linebreaks with 2-times intendation    
+        # First remove linebreaks with 2-times intendation (= continuation)    
         lines         = content.gsub(/\n((?!\n)\s){2}/, ' ').split(/\n/)
         name          = lines.shift.strip
         documentation = []
@@ -107,7 +225,7 @@ module Token
         
         lines.each do |line|          
           if TOKEN_W_TYPE_NAME.match(line)
-            # apply default-handler :typed_with_name to each child-line
+            # apply handler :typed_with_name to each child-line
             # @todo maybe we need a special way to select Children's Class?
             children << Handler.apply(:typed_with_name, tokenklass, line)
           else
@@ -134,94 +252,49 @@ module Token
       @@defaults[default_handler].call(*args)
     end
     
-    # Registering a new Tokenhandler
-    # ==============================
-    # It is possible to register your own Tokenhandlers and therefore extend the
-    # capabilities of this documentation-program.
-    #
-    # There are different types of handlers which can be used:
-    #
-    #   1. Default-handler
-    #   2. A handler for Typed-Token
-    #   3. A handler for Named-Typed-Tokens
-    #   4. Your custom handler (see second overload)
-    #
-    #
-    # @overload self.register(tokenname, type=nil)
-    #  
-    #  The first three of the handlers above can be registered with this
-    #  overload.
-    #  
-    #  The Default Handler
-    #  -------------------
-    #  The Default Header can be used for tokens like the one in the example above.
-    #  Trying to add a token like `@token` without adding a handler, you may get
-    #  an `exception` like:
-    #  
-    #       #=> Token::NoTokenHandler: No Tokenhandler for: token
-    #       #     from lib/token/container.rb:41:in process_token
-    #  
-    #  So we better register a handler for that token:
-    #  
-    #      Token::Handler.register :token
-    #  
-    #  As you can see **the second argument can be ommitted** to use a **default 
-    #  handler**. This default handler cannot parse typelists or tokennames, it
-    #  only saves the content of the token to the struct {Token::Handler::Token Token}.
-    #  
-    #  This Default Handler is enough for tokens like `@todo` or `@note`. But for
-    #  more complex Tokens we need some other handlers.
-    #  
-    #  Handler for Typed-Tokens
-    #  ------------------------
-    #  Typed tokens look like `@return [Foo, Bar] This is the description` - Additional
-    #  to their **default content** they specify the possible Types.
-    #  
-    #  To register a typed-token, you only need to add a second argument:
-    #  
-    #       Token::Handler.register :return, :typed
-    #  
-    #  The {Token::Handler::TypedToken typed-token struct}, pretty much looks like 
-    #  the default one.
-    #  
-    #       #=> #<struct Token::Handler::TypedToken types=["Foo", "Bar"], content="This is the description\n">
-    #
-    #  Handler for Typed-Named-Tokens
-    #  ------------------------------
-    #  They are much like **Typed-Token-Handlers**. They are needed for Tokenlines
-    #  like `@param [String] my_param This is a param`. They are registered with
-    #  `:typed_with_name` as the second argument:
-    #  
-    #       Token::Handler.register :param, :typed_with_name
-    #  
-    #  @param [String, Symbol] tokenname
-    #  @param [:typed, :typed_with_name, nil] type
+    def self.add_default_handler(name, &block)
+      @@defaults[name] = block;
+    end
+    
+    # It is possible to register your own Tokenhandlers and therefore extend the capabilities of 
+    # this documentation-tool (See: {file:CUSTOMIZE.md CUSTOMIZE}).
     #
+    # There are different types of handlers which can be used out of the box. Further documentation
+    # about the default handlers can be found {Token::Handler in the introduction}.
     #
-    # @overload self.register(tokenname, &handler)
-    #  
-    #  Writing your own custom Token-Handler
-    #  -------------------------------------
-    #  By adding a block in the Tokenregistration you easily can build your own
-    #  Tokenhandler:
+    # Writing your own custom Token-Handler
+    # -------------------------------------
+    # By adding the optional block you easily can build your own Tokenhandler:
     #
-    #       Token::Handler.register(:my_own) do |token_klass, stringcontent|
-    #         # Do something with token_id and stringcontent
-    #         # but don't forget to add the token like:
-    #         self.add_token(token_klass.new(:content => stringcontent)
-    #       end
+    #      Token::Handler.register(:my_own) do |token_klass, stringcontent|
+    #        # Do something with token_klass and stringcontent
+    #        # but don't forget to add the token like, if you want to access it from the templates:
+    #        # token_klass will be Token::MyOwnToken, which is dynamically created during registration
     #
-    #  Because the token processing is done in the **context of the CodeObject** you
-    #  can easily extend or manipulate the Objects.
-    #  
-    #  If you want to assure, that the object you are working on has a specific type
-    #  (for example a Function) add the following line to your handler:
+    #        self.add_token(token_klass.new(:content => stringcontent)
+    #      end
     #
-    #       has_to_be_a CodeObject::Function
+    # Because the token processing is done in the **context of the CodeObject** you
+    # can easily extend or manipulate the Object.
     #
-    #  @param [String, Symbol] tokenname
-    #  @yield [tokenklass, stringcontent] Your custom tokenhandler
+    # @param [String, Symbol] tokenname
+    # @param [Hash] options
+    # @option options [Symbol] :handler (:text_only)
+    # @option options [Symbol, String] :template (:default) The template for this token-collection
+    # @option options [Hash] :html ({}) Attributes which can be added to the html-representation of 
+    #   this token. For example use 
+    #       :html => { :class => 'big_button' } 
+    #   to add the class `.big_button` to the html-element. Please note, that your template has to 
+    #   render the html-attributes explicilty. For example by adding 
+    #       <div <%= attributize token.html %>>...</div>
+    # @option options [Symbol] :area (:body) The area the tokens will be rendered in. The default 
+    #   templates make use of (:notification|:body|:sidebar|:footnote), but you can use any symbol 
+    #   here.
+    # @option options [String] :description ("") The description specified here will appear in the
+    #   command-line output of `docjs tokens`
     # 
+    # @yield [tokenklass, stringcontent] Your custom tokenhandler
+    # @see Token::Token
     def self.register(tokenname, options = {}, &handler)
       
       tokenname = tokenname.to_sym   
@@ -238,7 +311,8 @@ module Token
       end      
       
       # Dynamically create Class named TokennameToken
-      klass = Token.const_set "#{tokenname.to_s.capitalize}Token", Class.new(Token)
+      camelcased = tokenname.to_s.capitalize.gsub(/_\w/){|w| w[1].capitalize}
+      klass = Token.const_set "#{camelcased}Token", Class.new(Token)
       
       klass.process_options options.merge({
       
@@ -250,7 +324,9 @@ module Token
       @@handlers[tokenname] = klass
     end
     
-    # Remove a registered handler from the list
+    # Remove a registered handler from the list.
+    # 
+    # @todo remove symbol `Token::TokennameToken`
     #
     # @example
     #   Token::Handler.register :foo
@@ -259,11 +335,7 @@ module Token
     # @param [String, Symbol] tokenname
     def self.unregister(tokenname)
       @@handlers.delete(tokenname.to_sym)
-    end
-    
-    def self.add_default_handler(name, &block)
-      @@defaults[name] = block;
-    end
+    end    
     
     protected