docjs 0.1

data/lib/code_object/converter.rb

@@ -0,0 +1,48 @@
+# ../data.img#1769990:1
+require_relative 'function'
+require_relative 'exceptions'
+require_relative 'type'
+
+module CodeObject
+
+
+  # here the dependencies to {Dom::Node} and {Parser::Comment} should be described
+  module Converter
+  
+    attr_reader :code_object, :path
+
+    def to_code_object
+
+      # 1. Create a new CodeObject from Type-Token   
+      @code_object = Type.create_matching_object(@tokenlines) or return nil
+            
+      # join all documentation-contents
+      @code_object.docs = @doclines.join ''     
+      
+      # move meta-information from comment to code_object
+      # (This includes filepath, source and line_start
+      @code_object.clone_meta(self)
+           
+      # 2. Process Tokenlines with registered handlers
+      @code_object.process_tokens(@tokenlines)
+      
+      # 3.Continue with all children of this comment and add them as
+      #   child nodes
+      convert_children { |child| @code_object.add_node(child) }
+      
+      return @code_object
+    end        
+    
+    protected
+
+    
+    # recursivly process all child-tokens
+    def convert_children
+      @children.each do |child_comment|
+        code_object = child_comment.to_code_object
+        yield(code_object) unless code_object.nil?
+      end
+    end
+    
+  end
+end

data/lib/code_object/exceptions.rb

@@ -0,0 +1,5 @@
+module CodeObject
+  
+  class MultipleTypeDeclarations < Exception; end
+
+end

data/lib/code_object/function.rb

@@ -0,0 +1,84 @@
+# ../data.img#1858563:1
+require_relative 'object'
+
+module CodeObject
+
+  class Function < CodeObject::Object
+   
+    token_reader :params, :param
+    token_reader :returns, :return
+  
+    def constructor?
+      @constructor || false
+    end
+    
+    # @todo i need a @prototype token in object
+    def prototype
+      children[:prototype]
+    end  
+  
+  end 
+  
+end
+
+CodeObject::Type.register :function, CodeObject::Function
+Token::Handler.register :function, :handler => :noop, :area => :none
+
+# @todo rewrite as default-handler, because this looks a little distracting
+module Token::Handler
+
+  # @todo maybe allow multipled nested layers of params by parsing them recursivly
+  register :param, :area => :body do |tokenklass, content|
+
+    # We want to support either named-typed-tokens like
+    #  @param [Foo] barname some description
+    #
+    # or multiline tokens like:
+    #  @param configs
+    #    [String] foo some string
+    #    [Bar] bar and another one
+    #
+    #
+    # if out content matches something with `[` at the beginning, it seems to be
+    # a normal named-typed-token
+    # it's a little tricky because we still want to allow multiline descriptions of each param
+    def parse_token(content)  
+      typestring, name, content = TOKEN_W_TYPE_NAME.match(content).captures
+      types = typestring.split /,\s*/
+      Token::Token::ParamToken.new(:name => name, :types => types, :content => content)
+    end
+    
+    # it's @param [String] name some content
+    if content.lines.first.match TOKEN_W_TYPE_NAME
+      self.add_token parse_token(content)
+    
+    # it maybe a multiline
+    else
+      lines = content.split(/\n/)
+      name = lines.shift.strip
+      types = ['PropertyObject']
+      
+      # now split line at opening bracket, not at line-break to enable multiline properties
+      children = lines.join("\n").strip.gsub(/\s+\[/, "<--SPLIT_HERE-->[").split("<--SPLIT_HERE-->")
+   
+      children.map! do |child|
+        parse_token(child)
+      end
+      
+      self.add_token tokenklass.new(:name => name, :types => types, :children => children)
+    end   
+  end
+
+
+end
+
+Token::Handler.register :return, :handler => :typed
+Token::Handler.register :throws, :handler => :typed
+
+# MethodAlias
+CodeObject::Type.register :method, CodeObject::Function
+Token::Handler.register :method, :handler => :noop, :area => :none
+
+# @constructor Foo.bar
+CodeObject::Type.register :constructor, CodeObject::Function
+Token::Handler.register(:constructor) { |token, content| @constructor = true }

data/lib/code_object/object.rb

@@ -0,0 +1,18 @@
+# ../data.img#1858561:1
+require_relative 'base'
+require_relative 'type'
+
+module CodeObject
+
+  class Object < CodeObject::Base
+    
+    token_reader :props, :prop
+    
+  end
+    
+end
+
+CodeObject::Type.register :object, CodeObject::Object
+Token::Handler.register :object, :handler => :noop, :area => :none
+
+Token::Handler.register :prop, :handler => :typed_with_name

data/lib/code_object/type.rb

@@ -0,0 +1,43 @@
+require_relative 'exceptions'
+
+module CodeObject 
+
+  module Type
+  
+    @@types = {}
+  
+    def self.register(tokenid, klass)
+      @@types[tokenid.to_sym] = klass
+    end  
+    
+    def self.create_matching_object(tokenlines)          
+      klass = self.find_klass(tokenlines) or return nil
+      self[klass.token].new(klass.content)
+    end
+    
+    protected
+    
+    def self.[](tokenid)
+      @@types[tokenid.to_sym]
+    end
+    
+    def self.include?(tokenid)
+      @@types.has_key? tokenid.to_sym
+    end
+    
+    def self.find_klass(tokenlines)
+      klass = tokenlines.select {|t| self.include? t.token }
+      
+      if klass.size > 1
+        raise CodeObject::MultipleTypeDeclarations.new, "Wrong number of TypeDeclarations: #{klass}"
+      elsif klass.size == 0
+        # it's not possible to create instance
+        return nil
+      end
+      
+      klass.first
+    end
+    
+  end
+  
+end

data/lib/configs.rb

@@ -0,0 +1,53 @@
+module Configs
+
+  def self.set(sym_or_hash, value = nil)
+
+    unless sym_or_hash.is_a? Hash
+      sym_or_hash = { sym_or_hash => value }  
+    end
+
+    sym_or_hash.each_pair do |attr, value|
+      set_attribute(attr, value)
+    end
+  end
+
+  def self.attributes
+    class_variables.map do |var|
+      var.to_s.scan(/@@(.*)/).first.first.to_sym
+    end
+  end
+  
+  def self.method_missing(method_name, *args)
+    nil
+  end
+  
+  def self.clear
+    class_variables.each do |var|
+      class_variable_set(var, nil)
+    end
+  end
+
+  protected
+
+  def self.set_attribute(key, value)
+
+    key = key.to_s
+
+    class_variable_set("@@#{key}", value)
+
+    class_eval <<-EOS
+      def self.#{key}
+        return @@#{key}
+      end
+    EOS
+    
+    if value.is_a? TrueClass or value.is_a? FalseClass
+      class_eval <<-EOS
+        def self.#{key}?
+          return @@#{key}
+        end
+      EOS
+    end
+  end
+
+end

data/lib/document/document.rb

@@ -0,0 +1,25 @@
+require_relative '../dom/dom'
+
+module Document
+
+  class Document
+  
+    include Dom::Node
+    
+    FILE_ENDINGS = /\.(markdown|mdown|md|mkd|mkdn)$/i
+    
+    attr_reader :name, :path, :content
+  
+    def initialize(path, content)
+      
+      path = File.basename(path).gsub(FILE_ENDINGS, '')
+      
+      # please do not confuse Filepath of Document (like docs/README.md) with path in Dom
+      # an .md will be stripped from the name and README.SOMEMORE.md can be used as path information
+      @path, @name, @content = ".#{path}", extract_name_from(path), content
+      super()
+    end
+    
+  end
+  
+end

data/lib/dom/dom.rb

@@ -0,0 +1,188 @@
+# ../data.img#1811391:1 && #1811396:1
+require_relative 'no_doc'
+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. 
+# 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})
+#  
+# The architecure of the Dom looks pretty much like this:
+#
+# ![Dom Architecture](../uml/Dom.svg)
+#
+# Take the following code-sample:
+#
+#     /**
+#      *  @function Foo.bar
+#      */
+#
+# The tree could look like:
+#  
+#     ROOT
+#      |
+#     Foo (not documented)
+#      |
+#     bar
+#    
+# Extending this example with two other comments
+#
+#     /**
+#      *  @object Foo
+#      */
+#     
+#     /**
+#      *  @object Foo.baz
+#      */
+#     
+# leads to this tree:
+#
+#       ROOT
+#        |
+#       Foo
+#       / \
+#     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.
+# 
+# Adding a new node to the tree is as simple as:
+# 
+#     Dom.add_node "Foo.bar", my_code_object
+#
+# 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}.
+# 
+# The tree above could be traversed using the following operations:
+# 
+#     Dom[:Foo]
+#     #=> #<CodeObject::Base:72903230 @parent=__ROOT__ @children=[:bar, :baz]> 
+#
+#     Dom[:Foo][:bar]
+#     #=> #<CodeObject::Base:72919910 @parent=Foo @children=[]>
+#
+#
+# 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.
+#     
+#     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.
+# 
+#     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"
+#   o3 = CodeObject::Object.new "bar"
+#   o4 = CodeObject::Object.new "baz"
+#   Dom.add_node "foo", o1
+#   Dom.add_node "foo.poo", o2
+#   Dom.add_node "foo.poo.bar", o3
+#   Dom.add_node "foo.poo.baz", o4
+#
+#   Dom.print_tree
+#   # -foo
+#   #   -poo
+#   #     -bar
+#   #     -baz
+#
+# Using the Dom for Documents
+# -------------------------------
+# The Dom can be used in **two** ways. Because Document-structure can be very similiar to the one
+# of our documentation-elements there are two kind of `root-nodes`:
+#
+# 1. {Dom.root}
+# 2. {Dom.docs}
+#
+# @see Dom::Node
+# @see Dom::NoDoc
+# @see CodeObject::Base
+# @see Document::Document
+module Dom
+
+  @@cache_path = File.expand_path("../../../cache/dom.cache", __FILE__)
+  
+  @@root = NoDoc.new('__ROOT__')
+  @@docs = NoDoc.new('__DOCUMENTS__')
+  
+  
+  # @group Dom Access-Methods
+  
+  # @return [Dom::NoDoc] The Dom's root-node
+  def self.root
+    @@root
+  end
+  
+  # @group Dom Management Methods
+  
+  # Reset the Dom to it's initial state by creating an empty {.root root-node}
+  def self.clear
+    @@root = NoDoc.new('__ROOT__')
+  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.
+  #
+  # 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
+    end
+  end
+  
+  # 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))
+  end
+  
+  # @group Document Objects
+  
+  # @return [Dom::NoDoc] the root of the Documenttree, consisting of {Document::Document}
+  def self.docs
+    @@docs
+  end
+  
+  protected
+  
+  # try to look up missing methods in @@root
+  def self.method_missing(method_name, *args)
+    if @@root.respond_to? method_name
+      @@root.send method_name, *args
+    else
+      raise NoMethodError.new(method_name.to_s)
+    end
+  end
+  
+end