docjs 0.2 → 0.2.1

data/lib/parser/comment.rb

@@ -3,7 +3,7 @@ require_relative '../code_object/converter'
 
 module Parser
 
-  # Together with {Parser::Coment} it acts as an **Interface** between {Parser} and {CodeObject}. 
+  # Together with {Parser::Comment} it acts as an **Interface** between {Parser} and {CodeObject}. 
   # Parser::Comment creates instances of Tokenline, which are then analysed by 
   # {Token::Container#process_token} 
   #

data/lib/parser/comment_parser.rb

@@ -2,8 +2,13 @@ require_relative 'comment'
 require_relative 'exceptions'
 
 module Parser
+  
+  # Creates an instance of {Parser::Comment}, then parses the content and adds the contained doc- 
+  # and tokenlines to it.
+  #
+  # @see Comment
   class CommentParser < StringScanner    
-
+  
     def initialize(input)
       super(input)
       @comment = Comment.new(input)
@@ -18,8 +23,7 @@ module Parser
     #
     # All other lines are interpreted as doclines
     #
-    # @return [Parser::Comment] Creates an instance of {Parser::Comment} and attaches all find doc- 
-    #   and tokenlines to it.
+    # @return [Parser::Comment] Attaches all found doc- and tokenlines to the instance of comment
     def parse
       # we don't want the linebreak of the comment start in our first docline
       # i.e. ignore '/**\n' 
@@ -51,7 +55,7 @@ module Parser
       end
     end
     
-    # Parses tokens, if the line begins with an @
+    # Parses tokens, if the line begins with an `@`
     #     @token_one some other text etc.
     #
     # The parser does the following to detect multiline tokens like:

data/lib/parser/meta_container.rb

@@ -1,6 +1,10 @@
 module Parser
 
-  # is included by {CodeObject::Base} and {Parser::Comment}
+  # Is included by {CodeObject::Base} and {Parser::Comment} and stores Metainformation like
+  #
+  # - **filepath** of the JavaScript-File, where the comment is extracted from
+  # - **source** of the JavaScript-Scope, which begins just after the comment ends.
+  # - **line_start** - Linenumber of the first scope-line
   module MetaContainer
   
     attr_reader :filepath, :source, :line_start

data/lib/parser/parser.rb

@@ -1,10 +1,8 @@
 require 'strscan'
 require_relative 'comment_parser'
 
-#
-# ![Parser Overview](../uml/Parser.svg)
-#
-#
+# @see Parser::Parser
+# @see Parser::CommentParser
 module Parser
 
   NO_BR = /((?!\n)\s)/
@@ -53,7 +51,35 @@ module Parser
     D_STRING     => D_STRING,
     REGEXP_START => REGEXP_END    
   } 
-   
+  
+  # ![Parser Overview](../img/md_parse_js.png)
+  #
+  # Turns the incoming javascript-source into a stream of {Parser::Comment comments}. Those comments 
+  # contain the parsed doclines, which are simply all lines found in the comment and all tokenlines.
+  #
+  # A tokenline starts with a token like `@token` and can span over multiple lines, if it is intended
+  # by two spaces.
+  # 
+  # The comment-scope (i.e. the javascript-language-scope beginning in the next line) will be preserved
+  # as `source` of the comment as well.
+  #
+  # For example it extracts to Comments from the following source
+  #     
+  #     /**
+  #      * @object Person
+  #      */
+  #     var Person = {}
+  #      
+  #     /**
+  #      * Some documentation here, and there
+  #      *
+  #      * @object Person.config
+  #      */
+  #     Person.config = {};
+  #     
+  #     #=> [#<Parser::Comment tokenlines=1 doclines=0>, #<Parser::Comment tokenlines=1 doclines=2>]
+  #
+  # @see Parser::CommentParser
   class Parser
   
     attr_reader :filepath, :offset
@@ -78,9 +104,10 @@ module Parser
     end  
     
     
-    # Recursivly parses the {#initialize given input} and thereby ignores strings.
+    # Recursivly parses the {#initialize given input} and thereby ignores strings and regular-
+    # expressions.
     #
-    # @todo Rewrite to use skip_intelligent_until
+    # @todo Rewrite to use {StringScanner#intelligent_skip_until}
     # @return [Array<Parser::Comment>] the parsed comment-stream
     def parse()
       @scanner.skip /\s/
@@ -108,6 +135,7 @@ module Parser
       end
     end
     
+    # Reads the contents of `path`, creates a new `Parser` and starts parsing all at once
     def self.parse_file(path)
       stream = File.read path
       Parser.new(stream, :filepath => path).parse
@@ -236,8 +264,6 @@ class StringScanner
     
     raise end_of_string_error(pattern) if self.matched.nil?
     
-    return if found.match pattern
-    
     Parser::NON_CODE_PATTERNS.each do |start_pattern, end_pattern|    
       if found.match start_pattern
         self.skip_escaping_until end_pattern
@@ -259,7 +285,7 @@ class StringScanner
     
     raise end_of_string_error(pattern) if self.matched.nil?
 
-    if self.matched.match /\\/
+    if self.matched.match /\\/ 
       self.getch
       skip_escaping_until(pattern)
     end    

data/lib/processor.rb

@@ -3,22 +3,52 @@ require_relative 'dom/dom'
 require_relative 'generator/generator'
 require_relative 'document/document'
 
-module Processor
-    
-  # @group Combined Stages
+# @note The prerequisites for Processor to work is that {Logger} and {Configs} are prepared and all 
+#   other components are already required. (Like the {Parser::Parser} and the {Dom}). For further
+#   information about how to set up the system, see {#setup_application}.
+#
+# The Processor is a component, which is essential for {DocJs} to fullfil it's tasks. While {DocJs}
+# serves as commandline-interface (CLI), the Processor is the heartpiece of DocJs and it's methods are
+# triggered directly by DocJs after having everything set up correctly.
+#
+# The Processing is divided into the following stages:
+module Processor 
   
-  def self.process_and_render
-    process_files_to_dom
-    perform_all_tasks
-  end
   
-  def self.process_files_to_dom(files = nil)
-    process_comments parse_files(files)
-  end 
+  # @group Stage #1 - Document Processing
+  
+  # For each specified Markdown-Document a new instance of {Document::Document} is created and filled
+  # with it's contents. Afterwards the document-nodes are added as children to `Dom.docs`.
+  # 
+  # ![Document Processing](img/md_process_documents.png)
+  # 
+  def self.prepare_documents
+    # underscores will be replaced with whitespaces as title
+    Configs.docs.each do |doc|
+    
+      doc_path = File.expand_path(doc, Configs.wdir)    
+      Logger.debug "Working with Document #{doc_path}"
+      
+      contents = File.read(doc_path)
+      
+      # Those documents get registered in a special {Dom::Node} Dom.docs
+      document = Document::Document.new(doc_path, contents)
+      Dom.docs.add_node(document.path, document)
+      
+      # The docs can be accessed via Dom later on
+    end
+  end  
+  
   
-  # @group Stage #1 - FileProcessor
+  # @group Stage #2a - File Processing
   
-  # Parsing Files and creating comment stream
+  # Process JavaScript files, whose filenames are stored in `Configs.files` (After having them 
+  # provided as commandline-options or in a `docjs.yml`-file)
+  # 
+  # Parses each JavaScript file and collects the found comments. After parsing everything all comments
+  # are returned as an Array.
+  #
+  #     [ *.js Files ] --(parses)--> [ Comments ]
   def self.parse_files(files = nil)
     files ||= Configs.files
         
@@ -35,45 +65,47 @@ module Processor
     return comments
   end  
   
-  # @group Stage #2 - CommentProcessor
+  
+  # @group Stage #2b - Comment Processing
   
   # Processing comment-stream and convert to {CodeObject CodeObjects}
-  # This stage also adds the CodeObjects to Dom.
+  # This stage also adds the CodeObjects to {Dom}.
+  #
+  #     [ Comments ] --(converts to)--> [ CodeObject ] --(add to)--> [ Dom ]
   def self.process_comments(comments)
     
     comments = [comments] unless comments.is_a? Array
     
     comments.each do |comment|    
-      code_object = comment.to_code_object            # convert to code_object
+      code_object = comment.to_code_object                                # convert to code_object
       Logger.debug "Adding to Dom: #{code_object}"
-      Dom.add_node(code_object.path, code_object) unless code_object.nil?     # add to dom
+      Dom.add_node(code_object.path, code_object) unless code_object.nil? # add to dom
     end
-  end
-  
+  end  
   
-  # @group Stage #3 - TemplateProcessor  
+  # @group Stage #3 - Template Processing  
 
-  def self.perform_all_tasks
+  # Searches for all Generator-Classes, instantiates them and calls {Generator::Generator#perform} 
+  # to trigger the content-generation.
+  #
+  #     [ Generators ] --(uses)--> [ Dom ]
+  #            |
+  #            ---(generates)--> [ HTML-Output ]
+  def self.start_generators
     Generator::Generator.all.each { |task| task.new.perform }
   end
+ 
+ 
+  # @group Combined Stages
   
-  # @group Stage #4 - Document Processor
-    
-  def self.prepare_documents
-    # underscores will be replaced with whitespaces as title
-    Configs.docs.each do |doc|
-    
-      doc_path = File.expand_path(doc, Configs.wdir)    
-      Logger.debug "Working with Document #{doc_path}"
-      
-      contents = File.read(doc_path)
-      
-      # Those documents get registered in a special {Dom::Node} Dom.docs
-      document = Document::Document.new(doc_path, contents)
-      Dom.docs.add_node(document.path, document)
-      
-      # The docs can be accessed via Dom later on
-    end
+  # Combines Stages {.parse_files #2a}, {.process_comments #2b} and {.start_generators #3}
+  def self.process_and_render
+    process_files_to_dom
+    start_generators
+  end
+  
+  # Combines Stage {.parse_files #2a} and {.process_comments #2b}
+  def self.process_files_to_dom(files = nil)
+    process_comments parse_files(files)
   end
- 
 end

data/lib/renderer.rb

@@ -1,6 +1,31 @@
 require 'erb'
 require 'fileutils'
 
+# The Renderer is the heart-piece of each {Generator::Generator}, but can also be used without them.
+# It uses ERB-Templates, which are being rendered with a binding to the Renderer-instance.
+#
+# It's only method {#render} can be used in multiple ways, which are explained {#render here}.
+# The Renderer is automatically been set up by the Generator, but to understand how it works we
+# may setup it ourselves like:
+#
+#     my_renderer = Renderer.new 'my/template/path', 'layout/application'
+#     my_renderer.render 'test', :to_file => 'output.html'
+#
+# This will render the template `my/template/path/test.html.erb` in the layout 
+# `my/template/path/layout/application.html.erb` and saved to `output.html`.
+#
+# Most of the time, as with Generators, the renderer will be extended and used like:
+#
+#     class MyRenderer < Renderer
+#  
+#        def initialize
+#          super('my/template/path', 'layout/application')
+#        end
+#
+#        def index
+#          render 'test', :to_file => 'output.html'
+#        end
+#      end
 class Renderer
 
   def initialize(default_path, layout)
@@ -8,7 +33,81 @@ class Renderer
     @_layout = layout
   end
 
-  # Pretty much inspired by Ruby on Rails
+  # @overload render(template, *opts)
+  #   Options **opts**:
+  #   
+  #   - :layout (String) Default is specified in constructor. For example `'json'` or `'application'`
+  #   - :to_file (String) Optional file-path to save the output to.   
+  #   
+  #   @param [String, Symbol] template Template-file **without** file-extension. (Like `index` => `index.html.erb`)
+  #   @param [Hash] opts
+  #   @return [String, nil] the rendered output
+  #
+  #
+  # @overload render(:partial => template, :collection => [...])
+  #   For each item of `collection`, the partial will be rendered once. The output consists of all
+  #   those concatenated render-passes.
+  #   The value of each item will be bound to a local-variable called like the partial, without leading
+  #   _. (i.e. if partial-name = "_test.html.erb" the variable is called `test`
+  #     
+  #   Options **opts**:
+  #   
+  #   - :template (String, Symbol) Template-file **without** file-extension. (Like `index` => `index.html.erb`)
+  #   - :collection (Array)
+  #   
+  #   @param [Hash] opts
+  #   @return [String] the rendered output
+  #
+  #
+  # @overload render(:partial => template, :locals => {...})
+  #   Each key of `locals` will be set to it's value in the local-binding of the partial.
+  #    
+  #   Options **opts**:
+  #
+  #   - :template (String, Symbol) Template-file **without** file-extension. (Like `index` => `index.html.erb`)
+  #   - :locals (Hash) Hash of variables, which will be available via local-variables in the partial-binding    
+  #   
+  #   @param [Hash] opts
+  #   @return [String] the rendered output
+  #
+  #
+  # @example simple rendering
+  #   render 'test', :layout => nil #=> returns a string, containing the rendered template 'test.html.erb'
+  #
+  # @example rendering within a layout
+  #   # layout/app.html.erb
+  #   <html>
+  #      <%= yield %>
+  #   </html>
+  #   
+  #   # MyCustomRenderer < Renderer
+  #   render 'test', :layout => 'layout/app' #=> renders 'test.html.erb' within 'app.html.erb'
+  #
+  # @example rendering a partial with collections
+  #   # _item.html.erb
+  #   <li><%= item %></li>   
+  #
+  #   # my_view.html.erb
+  #   <ul>
+  #     <%= render :partial => 'item', :collection => ["Foo", "Bar", "Baz"]
+  #   </ul>
+  #   
+  #   #=> <ul><li>Foo</li><li>Bar</li><li>Baz</li></ul>
+  #
+  # @example setting local-variables within a partial
+  #   # _item.html.erb
+  #   <strong><%= foo %></strong> <em><%= bar %></em>
+  #
+  #   # my_view.html.erb
+  #   <%= render :partial => 'item', :locals => { :foo => "Hello", :bar => "World" } %>
+  #   
+  #   #=> <strong>Hello</strong> <em>World</em>
+  #
+  # @example rendering to file
+  #   render 'my_test', :to_file => "test_output.html"
+  #
+  # @note Pretty much inspired by Ruby on Rails
+  # @see http://guides.rubyonrails.org/layouts_and_rendering.html
   def render(opt = nil, extra_options = {})
 
     # Prepare Options

data/lib/thor.rb

@@ -1,3 +1,5 @@
+# Extension of Thor to merge options from configuration-file and command line
+# @see https://github.com/wycats/thor/wiki
 class Thor
 
   protected

data/lib/token/container.rb

@@ -1,7 +1,9 @@
 require_relative 'exceptions'
 
 module Token
-
+  
+  # Each {CodeObject} serves as Token::Container. This module encapsulates all required methods
+  # to {#process_token convert Tokenlines to Tokens}, {#add_token add Tokens} and {#token query the stored tokens}.
   module Container
     
     def initialize
@@ -45,12 +47,14 @@ module Token
       @tokens[tokenid] << token
     end
     
-    # @param [Parser::Tokenline] tokenline consisting of :token and :content
+    # tries to find matching tokenklass for token i.e. Token::Token::ParamToken for :param
     # then calls matching tokenhandler (if exists) with data in `this`-context
-    # @todo only raise error, if config is set to whiny
+    #
+    # @param [Parser::Tokenline] tokenline consisting of :token and :content
+    #
+    # @todo only throw NoTokenHandler, if this really is the problem
     def process_token(tokenline)
-    
-      # try to find matching tokenklass for token i.e. Token::Token::ParamToken for :param
+   
       begin
         camelcased = tokenline.token.to_s.capitalize.gsub(/_\w/){|w| w[1].capitalize}
         tokenklass = Token.const_get "#{camelcased}Token"

data/lib/token/handler.rb

@@ -6,9 +6,7 @@ require_relative '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)
-#
-# The illustration above shows the **two modules** included in {Token}:
+# There are **two modules** included in {Token}:
 #
 #   1. {Token::Handler}, which can be used to register new token-handlers.
 #   2. {Token::Container}, which is included in {CodeObject::Base} to add 

data/lib/token/token.rb

@@ -12,6 +12,8 @@ module Token
   #       :template    => :foo,
   #       :description => "Description" 
   #     })
+  #
+  # (That's basically everything, that is done internally while registering a Token)
   class Token
 
     attr_reader :name, :content, :types, :children