docjs 0.1.5 → 0.2

data/lib/code_object/base.rb

@@ -9,16 +9,6 @@ require_relative '../parser/meta_container'
 #
 module CodeObject
 
-  # Find all CodeObject-Types, that inherit from Base
-  # @return [Hash] like {:object => CodeObject::Object, :function => CodeObject::Function }
-  def self.all_types
-    Hash[self.constants
-             .map { |c| [c.to_s.downcase.to_sym, self.const_get(c)] }
-             .select { |klass| klass[1].class == Class and klass[1].ancestors.include? Base }
-        ]
-  end  
-
-
   class Base
 
     include Token::Container

data/lib/code_object/converter.rb

@@ -11,10 +11,10 @@ module CodeObject
 
     def to_code_object
 
-      # 1. Create a new CodeObject from Type-Token   
+      # 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
+      # join all documentation-contents and make them one text again
       @code_object.docs = @doclines.join ''     
       
       # move meta-information from comment to code_object
@@ -45,7 +45,7 @@ module CodeObject
     def find_type_for(tokenlines)
     
       # all_types returns a hash like {:object => CodeObject::Object ...}
-      available_types = CodeObject.all_types
+      available_types = Token::Handler.types
     
       types = tokenlines.select {|t| available_types.has_key? t.token }
       

data/lib/dom/dom.rb

@@ -4,14 +4,13 @@ require_relative 'exceptions'
 # Storing {CodeObject::Base Objects}
 # ==================================
 #
-# The datastructure is based on a treelike concept. Every new inserted 
-# {CodeObject::Base object} is represented by a {Dom::Node node} of the tree. 
+# The datastructure is based on a treelike concept. Every new inserted {CodeObject::Base object} is 
+# represented by a {Dom::Node node} of the tree. 
 # There are three types of nodes:
 #
 #   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})
+#   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:
 #
@@ -49,8 +48,8 @@ require_relative 'exceptions'
 #       / \
 #     bar baz
 #      
-# Now all nodes are documented (i.e. a CodeObject exists for every node) and `Foo`
-# contains two other CodeObjects. `bar` and `baz` are leafs of the tree.
+# Now all nodes are documented (i.e. a CodeObject exists for every node) and `Foo` contains two 
+# other CodeObjects. `bar` and `baz` are leafs of the tree.
 # 
 # Adding a new node to the tree is as simple as:
 # 
@@ -58,8 +57,8 @@ require_relative 'exceptions'
 #
 # Traversing the Tree
 # -------------------
-# There are several method, which you can use to navigate throught the dom. The
-# most important is the {Dom::Node#[] children selector}.
+# There are several method, which you can use to navigate throught the dom. The most important is 
+# the {Dom::Node#[] children selector}.
 # 
 # The tree above could be traversed using the following operations:
 # 
@@ -72,15 +71,14 @@ require_relative 'exceptions'
 #
 # The Root Node
 # -------------
-# The Dom inherits functionality from it's **root-node**. So all method's
-# invoked on the root node, can be expressed equivalent as member of the Dom.
+# The Dom inherits functionality from it's **root-node**. So all method's invoked on the root node, 
+# can be expressed equivalent as member of the Dom.
 #     
 #     Dom.root[:some_child] <=> Dom[:some_child]
 #     Dom.root.children <=> Dom.children
 #     Dom.root.print_tree <=> Dom.print_tree
 #
-# Please note, that some methods of the root-node are hidden behind direct
-# implementations.
+# Please note, that some methods of the root-node are hidden behind direct implementations.
 # 
 #     Dom.add_node != Dom.root.add_node 
 #
@@ -137,33 +135,38 @@ module Dom
   # Reset the Dom to it's initial state by creating an empty {.root root-node}
   def self.clear
     @@root = NoDoc.new('__ROOT__')
+    @@docs = NoDoc.new('__DOCUMENTS__')
   end
   
   # @group Caching Methods
   
-  # Serializes and dumps the complete Domtree (but without last_position) to the 
-  # specified `path`. If no `path` is given, the default `@@cache_path` will be 
-  # used instead.
+  # Serializes and dumps the complete Domtree to the specified `path`. If no `path` is given, the 
+  # default `@@cache_path` will be used instead.
   #
-  # This Method can be useful, to save a specific state of the Domtree to disk
-  # and reuse it later, without the need to reconstruct it from zero.
+  # This Method can be useful, to save a specific state of the Domtree to disk and reuse it later, 
+  # without the need to reconstruct it from zero.
   #
   # @note To recreate the Dom from the dump-file, use {.load}.
   #
   # @param [String] file the filepath, where to write the serialized data
   def self.dump(file = @@cache_path)
     File.open(file, 'w') do |f|
-      f.write Marshal.dump @@root
+      f.write Marshal.dump({ 
+        :root => @@root,
+        :docs => @@docs
+      })
     end
   end
   
-  # Loads the {.dump serialized Dom} and replaces the current root node with
-  # the one created from the file.
+  # Loads the {.dump serialized Dom} and replaces the current root node with the one created from 
+  # the file.
   #
   # @see .dump
   # @param [String] file the filepath from which to load the Dom
   def self.load(file = @@cache_path)
-    @@root = Marshal.load(File.read(file))
+    dom = Marshal.load(File.read(file))
+    @@root = dom[:root]
+    @@docs = dom[:docs]
   end
   
   # @group Document Objects

data/lib/dom/no_doc.rb

@@ -3,7 +3,7 @@ require_relative 'node'
 module Dom
   
   # NoDoc is used by {Dom} and {Dom::Node} to preserve the correct hierachy of
-  # the tree, while inserting nodes with non existing parents.
+  # the tree, while inserting nodes with non (or not yet) existing parents.
   #
   # For example let's add the node 'foo.bar.baz' in our empty Dom. This will 
   # result in the following tree:
@@ -12,7 +12,7 @@ module Dom
   #       -bar (NoDoc)
   #         -baz
   #
-  # If a documented
+  # If a documented node with the same path is inserted, the NoDoc-node will be replaced by it.
   class NoDoc
     include Node
     

data/lib/dom/node.rb

@@ -3,14 +3,13 @@ require_relative 'exceptions'
 
 module Dom
 
-  # Node can be seen as an **aspect** or feature of another Object. Therefore it can
-  # be mixed in to add node-functionality to a class.
+  # Node can be seen as an **aspect** or feature of another Object. Therefore it can be mixed in to 
+  # add node-functionality to a class.
   # Such functionality is used by {CodeObject::Base code-objects} and {Document::Document documents}.
   #
   # Instance Variables
   # ------------------
-  # The following instance-variables will be set while including Dom::Node into
-  # your class:
+  # The following instance-variables will be set while including Dom::Node into your class:
   #
   # - `@name` (should be already set in your including class)
   # - `@parent`
@@ -39,8 +38,9 @@ module Dom
   #   #  -foo
   #   #  -bar
   #  
-  # @note including Class should implement instance-variable @name
+  # @note including Class should set instance-variable @name
   # @see CodeObject::Base
+  # @see Document::Document
   # @see Dom
   module Node
 
@@ -55,8 +55,8 @@ module Dom
     
     # @group Initialization
     
-    # The 'constructor' of {Dom::Node}. It initializes all required 
-    # instance-variables (see {Dom::Node above}).
+    # The 'constructor' of {Dom::Node}. It initializes all required instance-variables. 
+    # (see {Dom::Node above}).
     def initialize
       super
       @children, @parent = {}, nil
@@ -65,9 +65,8 @@ module Dom
     
     # @group Traversing
     
-    # `node.parent` returns the parent {Dom::Node node}, if there is one.
-    # If no parent exists `nil` is returned. In this case `node` can be
-    # considered either as loose leave or root of the {Dom}.
+    # `node.parent` returns the parent {Dom::Node node}, if there is one. If no parent exists `nil` 
+    # is returned. In this case `node` can be considered either as loose leave or root of the {Dom}.
     #
     # @return [Dom::Node] the parent node, if one exists
     def parent
@@ -75,9 +74,8 @@ module Dom
     end
     
     
-    # searches all parents recursivly and returns an array, starting with the
-    # highest order parent (excluding the {Dom.root}) and ending with the  
-    # immediate parent.
+    # searches all parents recursivly and returns an array, starting with the highest order parent 
+    # (excluding the {Dom.root}) and ending with the immediate parent.
     #
     # @example
     #   o1 = CodeObject::Base.new :foo
@@ -105,7 +103,8 @@ module Dom
     end
     
     
-    # Get's the child of this node, which is identified by `path`
+    # Get's the child of this node, which is identified by `path`. Returns `nil? , if no matching 
+    # child was found.
     # 
     # @example childname
     #   Dom[:Core]             #=> #<CodeObject::Object:Core @parent=__ROOT__ …>
@@ -116,11 +115,11 @@ module Dom
     #
     # @overload [](childname)
     #   @param [String, Symbol] childname
-    #   @return <Dom::Node>
+    #   @return [Dom::Node, nil]
     #
     # @overload [](path)
     #   @param [String] path The path to the desired node
-    #   @return <Dom::Node>
+    #   @return [Dom::Node, nil]
     def [](path)
       return @children[path] if path.is_a? Symbol
       return @children[path.to_sym] if path.split(NS_SEP_STRING).size == 1
@@ -148,8 +147,7 @@ module Dom
       not (@children.nil? or @children.size == 0)
     end
     
-    # Finds all siblings of the current node. If there is no parent, it will 
-    # return `nil`.
+    # Finds all siblings of the current node. If there is no parent, it will return `nil`.
     #
     # @return [Array<Dom::Node>, nil]
     def siblings
@@ -239,14 +237,15 @@ module Dom
     # @group Manipulation
     
     # There are three different cases
-    #   1. Last Childnode i.e. ".foo"
-    #      -> Append node as child
-    #   2. absolute path i.e. "Foo"
-    #      -> delegate path resolution to Dom.root
-    #   3. relative path i.e. ".bar.foo"
-    #         a. if there is a matching child for first element, delegate
-    #            adding to this node
-    #         b. create NoDoc node and delegate rest to this NoDoc
+    #
+    # 1. Last Childnode i.e. ".foo"
+    #    -> Append node as child
+    # 2. absolute path i.e. "Foo"
+    #    -> delegate path resolution to Dom.root
+    # 3. relative path i.e. ".bar.foo"  
+    #    a. if there is a matching child for first element, delegate
+    #       adding to this node  
+    #    b. create NoDoc node and delegate rest to this NoDoc
     #
     #
     # @overload add_node(path, node)

data/lib/helper/helper.rb

@@ -4,58 +4,106 @@ require 'rdiscount'
 
 require_relative 'linker'
 
-# The Helpers are 'mixed' into your {Generator::Generator generator} and therefore can be used in all 
-# template-views.
+# The Helpers are 'mixed' into your {Generator::Generator generator} and therefore can be used in 
+# all template-views.
 # If you are searching for a method and don't know, where it may be implemented i suggest the 
 # following inheritence chain as your search-strategy:
 #
-#     Helper::IncludedHelpers → Generator::YourGenerator → Generator::Generator → Renderer
+#     Helper::IncludedHelpers -> Generator::YourGenerator -> Generator::Generator -> Renderer
 #
 # Somewhere at that chain you will find your desired function.
 module Helper
 
   # The Helper-methods in this module are globally used one and should not depend on the template
-  # you are using. You will find many html-helpers around here.
+  # you are using. You will find many html-helpers around here, that are inspired by rails.
   module Helper
  
     include Linker
     
-    def tag(sym, content = "", attrs = {})
+    # Creates a HTML-Tag and adds the attributes, specified with `attrs`
+    #
+    # @todo FIXME - not working with block, yet...
+    #   Rails incorporates a `capture` method, which captures the ERB-output of a block
+    #   maybe we can use something like that
+    #   `with_output_buffer` {http://apidock.com/rails/ActionView/Helpers/CaptureHelper/with_output_buffer}
+    #
+    # @example
+    #    tag :a, 'Hello', :href => 'http://foobar.com', :class => 'red_one'
+    #    #=> <a href="http://foobar.com" class="red_one">Hello</a>
+    #
+    # @param [Symbol, String] tagname
+    # @param [String] content
+    # @param [Hash<Symbol, String>] attrs
+    # @return [String] html-tag
+    #
+    # @see #attributize
+    def tag(tagname, content = "", attrs = {})
    
-      # @todo FIXME
+      # Not working with blocks!
       if block_given?
-        _erbout << "<#{sym.to_s} #{attributize(content)}>"        
+        _erbout << "<#{tagname.to_s} #{attributize(content)}>"        
         content = yield
-        _erbout << "</#{sym.to_s}>"
+        _erbout << "</#{tagname.to_s}>"
       else
-        "<#{sym.to_s} #{attributize(attrs)}>#{content}</#{sym.to_s}>"        
+        "<#{tagname.to_s} #{attributize(attrs)}>#{content}</#{tagname.to_s}>"        
       end     
     end    
     
-    def truncate(string, num = 150)
-      if string.length > num
-        string[0..num] + " &hellip;"
-      else
-        string
-      end
+    # Shortens the given string to the specified length and adds '...'
+    def truncate(string, length = 150)
+      string.length <= length ? string : string[0..length] + " &hellip;"
     end
     
+    # Creates a css-link tag for each input string. The resource will be linked relativly.
+    #
+    # @example
+    #   style 'foo', 'bar'
+    #   #=> <link rel='stylesheet' href='../css/foo.css'/>
+    #   #=> <link rel='stylesheet' href='../css/bar.css'/>
+    #
+    # @param [String] basename of the css-file (without extension)
+    # @return [String] html-element to include the css-file
     def style(*args)
-      html = ""
-      args.each do |path|
-        html += tag :link, "", :rel => 'stylesheet', :href => to_relative('css/'+path+'.css')
-      end
-      return html
+      args.map do |path|
+        tag :link, "", :rel => 'stylesheet', :href => to_relative('css/'+path+'.css')
+      end.join ''
     end
     
+    # Creates a javascript-tag for each input string to import the script. The resource will be 
+    # linked relativly.
+    #
+    # @example
+    #   script 'foo', 'bar'
+    #   #=> <script href='../js/foo.js'/>
+    #   #=> <script href='../js/bar.js'/>
+    #
+    # @todo because those js-files are all relative links, they could be joined together and packed
+    #   afterwards 
+    #
+    # @param [String] basename of the javascript-file (without extension)
+    # @return [String] html-element to include the javascript-file
     def script(*args)
-      html = ""
-      args.each do |path|
-        html += tag :script, "", :src => to_relative('js/'+path+'.js')
-      end
-      return html
+      args.map do |path|
+        tag :script, "", :src => to_relative('js/'+path+'.js')
+      end.join ''
     end
     
+    # Removes intendation from the sources and generates a code-tag with all the required classes
+    # to make the javascript-syntax-highlighter work.
+    #
+    # @example
+    #   code "  function() {}"
+    #   #=> <code class="brush:js first-line:1">function(){}</code>
+    #
+    # @example
+    #   code "  function() {}", :firstline => 15
+    #   #=> <code class="brush:js first-line:15">function(){}</code>
+    #
+    # @param [String] source
+    # @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
+    # @return [String] the html-code-element 
     def code(source, opts = {})
 
       # defaults
@@ -66,21 +114,24 @@ module Helper
       intendation = source.lines.map {|line| line.match(/(^\s+)/) && line.match(/(^\s+)/).captures.first.size || 0 }.min
       
       # @todo there has to be a better way for that      
-      tag :code, h(source.lines.map { |line| line[intendation .. line.size] }.join("")), :class => "#{opts[:class]} brush:js first-line:#{opts[:firstline]}" 
-    end
-    
-    def to_html(markdown_text, *markdown_opts)
-      replace_links RDiscount.new(markdown_text, *markdown_opts).to_html
-    end
-    
-    def toc(markdown_text)
-      RDiscount.new(markdown_text, :generate_toc).toc_content
+      tag :code, h(source.lines.map { 
+        |line| line[intendation .. line.size] 
+      }.join("")), :class => "#{opts[:class]} brush:js first-line:#{opts[:firstline]}" 
     end
     
+    # Escapes any html-elements in the given string
+    #
+    # @param [String] to_escape
+    # @return [String] the escaped string
     def h(to_escape)
       CGI.escapeHTML(to_escape)
     end
     
+    # Takes an absolute path and converts it to a relative one, comparing it to the **current
+    # output path**.
+    #
+    # @param [String] path
+    # @return [String] relative path
     def to_relative(path)
     
       path = Pathname.new(path)
@@ -95,8 +146,44 @@ module Helper
       
       Logger.debug "Relative path '#{path}' from '#{base}'"
       path.relative_path_from(base).to_s
-    end
-    
+    end    
+
+    # 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
+    #
+    # @example render tokens of notification-area
+    #   render_tokens :of => code_object, :in => :notification
+    #
+    # @example exclude `@deprecated`-Tokens from output
+    #   render_tokens :of => code_object, :in => :body, :without => [:deprecated]
+    #
+    # @example use special default-template
+    #   render_tokens :of => code_object, :in => :sidebar, :template => 'sidebar' 
+    #
+    # @param [Hash] opts
+    # @option opts [CodeObject::Base] :of The object, which contains the tokens, to be rendered
+    # @option opts [Symbol] :area The area to filter the tokens for
+    # @option opts [Array<Symbol>, nil] :without Tokennames to be excluded from the output
+    # @option opts [Symbol, String, nil] :template If you wan't to overwrite the default template
+    #   you can use this option. (Note: templates, specified at token-registration have higher
+    #   precedence, than this option)  
     def render_tokens(opts = {})
     
       code_object = opts[:of] or raise Exception.new("Parameter :of (CodeObject) required")
@@ -124,9 +211,47 @@ module Helper
       rendered
     end
     
+    # Takes a hash as input and returns a string, which can be included in a html tag.
+    #
+    # @example
+    #   attributize :style => 'border: none;', :class => 'foo' #=> 'style="border: none;" class="foo"'
+    #
+    # @param [Hash] hash
+    # @return [String]
     def attributize(hash)
       hash.map{|k,v| "#{k}=\"#{v}\""}.join ' '
     end
     
+    # @group Markdown
+    
+    # Converts input text to html using RDiscount. Afterwards all contained links are resolved and
+    # replaced.
+    #
+    # More information about the markdown_opts can be found at the
+    # {http://rubydoc.info/github/rtomayko/rdiscount/master/RDiscount RDiscount-rdoc-page}.
+    #
+    # @param [String] markdown_text plain text with markdown-markup
+    # @param [Symbol, nil] markdown_opts 
+    # @return [String] converted html
+    def to_html(markdown_text, *markdown_opts)
+      replace_links RDiscount.new(markdown_text, *markdown_opts).to_html
+    end
+    
+    # Can be used to generate a table of contents out of a markdown-text.
+    # The generated toc contains links to the document-headlines.
+    # To make this links actually work you need to process the document with the
+    # :generate_toc flag, too.
+    #
+    # @example
+    #   <%= toc(my_text) %>
+    #   ...
+    #   <%= to_html my_text, :generate_toc %>
+    #
+    # @param [String] markdown_text
+    # @return [String] html table of contents
+    def toc(markdown_text)
+      RDiscount.new(markdown_text, :generate_toc).toc_content
+    end
+    
   end
 end