docjs 0.2 → 0.2.1

data/lib/boot.rb

@@ -11,9 +11,18 @@ require_relative 'code_object/base'
 require_relative 'dom/dom'
 require_relative 'processor'
 
+# `#setup_application` is called during the initialization process of DocJs within {DocJs#docjs}
+#
+# ![Boot Activity Diagram](img/md_boot.svg)
+#
+# It is responsible to configure the two application-wide Singleton Objects {Logger} and {Configs}
+# and fill {Configs} with the given commandline arguments.
+#
+# If the user is using it's own custom templates (see {file:CUSTOMIZE.md}) those templates will be
+# included before the processing can begin.
 def setup_application(options = {})
         
-  # initialize Logger
+  # Initialize Logger
   Logger.setup :logfile => (options[:logfile] && File.expand_path(options[:logfile], Dir.pwd)),
                :level   => (options[:loglevel] || :info).to_sym
   
@@ -21,10 +30,11 @@ def setup_application(options = {})
   
   # Process option-values and store them in our Configs-object
   Configs.set :options      => options, # Just store the options for now
+  
+              # Set the paths  
               :wdir         => Dir.pwd, # The current working directory
               :output       => File.absolute_path(options[:output]),
               :templates    => File.absolute_path(options[:templates]),
-              :includes     => (options[:includes] && File.absolute_path(options[:includes])),
               :files        => (options[:files] && options[:files].map {|path| Dir.glob(path) }.flatten),
               :docs         => (options[:docs] && options[:docs].map {|path| Dir.glob(path) }.flatten)
   

data/lib/code_object/base.rb

@@ -3,10 +3,6 @@ require_relative '../token/handler'
 require_relative '../dom/dom'
 require_relative '../parser/meta_container'
 
-#
-# ![Code Object Overview](../uml/CodeObject.svg)
-#
-#
 module CodeObject
 
   class Base

data/lib/code_object/converter.rb

@@ -2,8 +2,6 @@ require_relative 'exceptions'
 
 module CodeObject
 
-  # here the dependencies to {Dom::Node} and {Parser::Comment} should be described
-  #
   # Converts a comment to a code_object and therefor is included in {Parser::Comment}
   module Converter
   
@@ -11,7 +9,7 @@ module CodeObject
 
     def to_code_object
 
-      # 1. Create a new CodeObject from Type-Token like @function → CodeObject::Function 
+      # 1. Create a new CodeObject from Type-Token like @function -> CodeObject::Function 
       @code_object = find_type_for(@tokenlines) or return nil
             
       # join all documentation-contents and make them one text again
@@ -51,16 +49,17 @@ module CodeObject
       
       if types.size > 1
         raise CodeObject::MultipleTypeDeclarations.new, "Wrong number of TypeDeclarations: #{types}"
-      elsif types.size == 0
+      elsif types.size == 1
+        type = types.first
+        
+        # Get Class and instantiate it with content
+        klass = available_types[type.token]
+        return klass.new(type.content)
+        
+      else
         # it's not possible to create instance
         return nil
-      end
-      
-      type = types.first
-      
-      # Get Class and instantiate it with content
-      klass = available_types[type.token]
-      klass.new(type.content)
+      end      
     end    
   end
 end

data/lib/configs.rb

@@ -1,3 +1,31 @@
+# Systemwide Singleton, which can be used to store global configurations, like paths or some other
+# settings
+#
+# @example Usage
+#   Configs.set :foo, 123
+#   Configs.foo #=> 123
+#   
+#   Configs.set :foo => 456, :bar => "Hello World"
+#   Configs.foo #=> 456
+#   Configs.bar #=> "Hello World"
+#   
+#   Configs.baz #=> nil
+#
+# @example List all configs
+#   Configs.attributes #=> { :foo => 456, :bar => "Hello World" }
+#
+# @example Real dump of Configs, after setting up DocJs
+#   Configs.attributes #=> [:root, :options, :wdir, :output, :templates, :files, :docs] 
+#   
+#   Configs.root       #=> #<Pathname:/path/to/application/root>
+#   Configs.options    #=>  {:files=>["test/js-files/core-doc.js"], :docs=>["test/docs/*.md"], 
+#                      #     :output=>"out", :templates=>#<Pathname:/path/to/templates>, 
+#                      #     :appname=>"Doc.js", :loglevel=>"debug"} 
+#   Configs.wdir       #=> "/path/to/working/directory"
+#   Configs.output     #=> "/path/to/output/directory"
+#   Configs.templates  #=> "/path/to/used/template/directory"
+#   Configs.files      #=> ["test/js-files/core-doc.js"] 
+#   Configs.docs       #=> ["test/docs/README.md", "test/docs/README.CONCEPT.md"]
 module Configs
 
   def self.set(sym_or_hash, value = nil)

data/lib/document/document.rb

@@ -2,6 +2,27 @@ require_relative '../dom/dom'
 
 module Document
 
+  # Document is used to represent Markdown-Files (which should provied further help to your 
+  # generated docs)
+  # Each given Markdown-File is converted in a {Document::Document} and then added to {Dom.docs}
+  # Like the {file:USE.md#Namespacing namespacing} in JavaScript-Comments there is a 
+  # naming-convention for Markdown-files if you wish to store them in a tree-like structure.
+  #
+  #     docs/README.md
+  #     docs/README.CONCEPT.md
+  #     docs/README.ARCHITECTURE.md
+  #
+  # will result in a tree:
+  #
+  #           Dom.docs
+  #              |
+  #            README
+  #          /        \
+  #     CONCEPT ARCHITECTURE
+  #
+  # @todo it would be much nicer, if a directory is provided in the CLI (like :docs => "/my/docs")
+  #   that this tree-structure is reconstructed from the directory-structure. Naming files like
+  #   `My.Awesome.File.md` is not that elegant.
   class Document
   
     include Dom::Node

data/lib/dom/dom.rb

@@ -11,10 +11,6 @@ require_relative 'exceptions'
 #   1. {Dom::NoDoc Not documented nodes} that contain other nodes
 #   2. {Dom::Node Documented nodes}, that contain other nodes
 #   3. Leafs of the tree, without children. (Those leafs have to be {Dom::Node documented nodes})
-#  
-# The architecure of the Dom looks pretty much like this:
-#
-# ![Dom Architecture](../uml/Dom.svg)
 #
 # Take the following code-sample:
 #
@@ -82,11 +78,6 @@ require_relative 'exceptions'
 # 
 #     Dom.add_node != Dom.root.add_node 
 #
-# For the example above the full UML-Graph, including the root-node, could look
-# like:
-#
-# ![dom tree sample](../uml/dom_tree_sample.svg)
-# 
 # @example Adding some Nodes
 #   o1 = CodeObject::Object.new "foo"
 #   o2 = CodeObject::Object.new "poo"

data/lib/generator/generator.rb

@@ -4,9 +4,84 @@ require_relative '../helper/helper'
 
 module Generator
 
+  # If you already familiar with Ruby on Rails: Generators are pretty much like Controllers in Rails.
+  # That's like in Rails:
+  #
+  # - They use the existing data-model (The {Dom} in our case)
+  # - They start the rendering process in a view, by calling {Renderer#render render}.
+  # - If you want to make use of data in a view, you can store it in an instance-variable, like `@nodes`
+  # - Helpers are included in the generator, so you can utilize their messages in views
+  #
+  # The major difference between controllers in Rails and generators in DocJs is, that DocJs triggers
+  # all generators one after another and there is no real interaction between the views and the
+  # generator.
+  #
+  # In other words, after collecting all necessary informations about the JavaScript-Files and
+  # Markdown-Documents DocJs uses the Generators to create the final output.
+  #
+  # @example a simple generator
+  #   module Generator
+  #     class MyTestGenerator < Generator
+  #       # For more information about those methods, see section Generator-Specification methods
+  #       describe     'does awesome things'
+  #       layout       'application'
+  #       start_method :go
+  #       templates    '/views/special_ones'
+  #        
+  #       protected
+  #
+  #       def go       
+  #         in_context Dom.root do
+  #           @elements = []
+  #           Dom.root.each_child do |child|
+  #             @elements << child unless child.is_a? Dom::NoDoc
+  #           end
+  #           
+  #           render 'my_view', :to_file => 'output_file.html'
+  #         end    
+  #       end
+  #     end
+  #   end
+  #
+  # The following image should help you to get a general overview, how the components of DocJs interact:
+  #
+  # ![Render Flow](../img/md_render_flow.png)
+  #
+  # One may notice, that {Renderer} and {Generator::Generator} are not that separable, as shown in this
+  # image. In fact the concrete Generator (like {Generator::ApiIndexGenerator}) inherits from 
+  # {Generator::Generator}, which in turn inherits from {Renderer}.
+  # So we've got an inheritence-chain like:
+  #
+  #     Generator::ApiIndexGenerator < Generator::Generator < Renderer
+  #
+  # Helpers
+  # -------
+  # You can create your own helper functions, bundled in a custom helper-module. They automatically
+  # will be mixed in all Generators, as long as they match the following conditions:
+  #
+  # - Your module has to be a Submodule of Helper
+  # - Your code has to be included somewhere (i.e. `require 'my_helper'` in `application.rb`)
+  # 
+  # For example your helper could look like:
+  # 
+  #     # TEMPLATE_PATH/helpers/my_helper.rb
+  #     module Helper::MyHelper       
+  #       def my_greeter
+  #         "Hello Woooorld"
+  #       end       
+  #     end
+  #     
+  #     # TEMPLATE_PATH/application.rb
+  #     require_relative 'helpers/my_helper'
+  #
+  # Then you could use them in your Generator or in your Views
+  #
+  #     # TEMPLATE_PATH/views/template.html.erb
+  #     <h1><%= my_greeter %></h1>
   class Generator < Renderer
   
     def initialize
+      # At this point we pass the configurations to our Parent `Renderer`
       super(Configs.templates + configs(:templates), configs(:layout))
       
       # include all Helpers
@@ -18,6 +93,90 @@ module Generator
       @_context = Dom.root
     end
     
+    # @group Generator-Specification methods
+    
+    # This description is used in the cli-command `docjs generators` to list all generators and their
+    # descriptions
+    #
+    # @param [String] desc A short description of this generators task
+    def self.describe(desc)
+      self.set_config(:description, desc.to_s)
+    end
+  
+    # Specifies which layout should be used to render in (Default is `nil`)
+    #
+    # @param [String] layout_view
+    def self.layout(layout_view)    
+      unless layout_view.nil?
+        self.set_config(:layout, 'layout/' + layout_view)
+      else
+        self.set_config(:layout, nil)
+      end
+    end
+  
+    # Which method should be invoked, if generator is executed (Default is `:index`)
+    #
+    # @param [String, Symbol] method
+    def self.start_method(method)
+      self.set_config(:start_method, method.to_sym)
+    end
+     
+    # The path to your views (Default is `/views`)
+    #
+    # You can use this method, to specify a special template path, for example if you want to use
+    # a subdirectory of your views, without always having to provide the full path in all `render`-calls
+    #
+    # @note the layout-path is always relative to your specified path (i.e. `layout 'application'`
+    #   and `templates 'my_custom'` will result in a required layout file with a path like
+    #   `my_custom/layout/application.html.erb`
+    #
+    # @param [String] path_to_views Relative path from your scaffolded template-directory, but with 
+    #   a leading `/`, like `/views/classes`
+    def self.templates(path_to_views)
+      self.set_config(:templates, path_to_views)
+    end  
+    
+    # @note not neccesarily needed, because all Helpers are included by default
+    #
+    # Can be used to include a helper in a Generator 
+    def self.use(helper_module)
+     include helper_module
+    end
+    
+    # @group Context manipulation- and access-methods
+    
+    # Modyfies the Dom-resolution-context {#context} to `new_context`, while in `&block`. After 
+    # leaving the block, the context will be switched back.
+    #
+    # @param [Dom::Node] new_context The new context
+    # @yield block The block, in which the context is valid
+    def in_context(new_context, &block)
+      old_context = @_context
+      @_context = new_context
+      yield
+      @_context = old_context
+    end
+    
+    # Retreives the current Dom-resolution-context, which can be specified by using {#in_context}
+    #
+    # @return [Dom::Node] the context, to which all relative nodes should be resolved
+    def context
+      @_context
+    end
+    
+    # Resolves a nodename in the specified context, by using {Dom::Node#resolve} on it.
+    #
+    # @param [String] nodename
+    # @return [Dom::Node, nil]
+    # @see Dom::Node#resolve
+    def resolve(nodename)
+      @_context.resolve nodename
+    end
+    
+    # @group System-Methods
+    
+    # Calls always the specified `:start_method` on this Generator. (Default for :start_method is
+    # 'index')
     def perform
       
       unless self.respond_to? configs(:start_method)
@@ -27,19 +186,17 @@ module Generator
       self.send configs(:start_method)
     end
     
-    def context
-      @_context
-    end
-    
+    # Is used by {DocJs#generators} to provide a list of all generators and their descriptions
+    #
+    # @return [String] description, which has been previously entered using `.describe`
     def self.description
        configs(:description)
     end
     
-    # not neccesarily needed, because all Helpers are included by default
-    def self.use(helper_module)
-     include helper_module
-    end
-    
+    # Returns all Generators, by finding all constants in the Generator-Module and filtering them
+    # for classes with parent {Generator::Generator}.
+    #
+    # @return [Array<Generator>]
     def self.all
       # Otherwise we don't get the global Generator-Module
       gen_module = Object.const_get(:Generator)
@@ -50,29 +207,6 @@ module Generator
     
     protected
     
-    # @group Generator-Specification methods
-    
-    def self.describe(desc)
-      self.set_config(:description, desc.to_s)
-    end
-  
-    def self.layout(layout_view)    
-      unless layout_view.nil?
-        self.set_config(:layout, 'layout/' + layout_view)
-      else
-        self.set_config(:layout, nil)
-      end
-    end
-  
-    def self.templates(path_to_templates)
-      self.set_config(:templates, path_to_templates)
-    end  
-    
-    def self.start_method(method)
-      self.set_config(:start_method, method.to_sym)
-    end
-    
-    
     # @group helper methods to make usage of class-variables work in **inheriting** classes
     
     def self.configs(attribute)
@@ -82,14 +216,14 @@ module Generator
       defaults = {:templates    => '/views',
                   :layout       => nil,
                   :description  => 'No description given.',
-                  :start_method => :perform_task }
+                  :start_method => :index }
       
       if self.class_variable_defined? key
         self.class_variable_get(key)
       else
         defaults[attribute.to_sym]
       end    
-    end
+    end 
     
     # the instance equivalent to get the class-variable of the **inheriting** class
     def configs(*args)
@@ -102,24 +236,5 @@ module Generator
       self.class_variable_set(key, value)
     end
     
-    
-    # @group context manipulation and access methods
-    
-    # maybe we can use this later on, while linking
-    def in_context(new_context, &block)
-      old_context = @_context
-      @_context = new_context
-      yield
-      @_context = old_context
-    end
-    
-    def context
-      @_context
-    end
-    
-    def resolve(nodename)
-      @_context.resolve nodename
-    end
-    
   end
 end

data/lib/helper/helper.rb

@@ -103,6 +103,9 @@ module Helper
     # @param [Hash] opts
     # @option opts [Numeric] :firstline (1) The line-numeration will start with that number 
     # @option opts [String] :class ("block") A optional css-class which can be added
+    #
+    # @see http://alexgorbatchev.com/SyntaxHighlighter
+    #
     # @return [String] the html-code-element 
     def code(source, opts = {})