docjs 0.1.2 → 0.1.3

data/lib/code_object/object.rb

@@ -15,4 +15,4 @@ end
 CodeObject::Type.register :object, CodeObject::Object
 Token::Handler.register :object, :handler => :noop, :area => :none
 
-Token::Handler.register :prop, :handler => :typed_with_name
+Token::Handler.register :prop, :handler => :typed_with_name

data/lib/helper/helper.rb

@@ -1,6 +1,7 @@
 # ../data.img#1800236:1
 require 'pathname'
 require 'rdiscount'
+require 'cgi'
 
 require_relative 'linker'
 
@@ -56,12 +57,17 @@ module Helper
       return html
     end
     
-    def code(source)    
+    def code(source, opts = {})
+
+      # defaults
+      opts[:firstline] ||=  1
+      opts[:class]     ||= "block"
+          
       # find minimal intendation
       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, source.lines.map { |line| line[intendation .. line.size] }.join(""), :class => 'block'
+      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)
@@ -72,6 +78,10 @@ module Helper
       RDiscount.new(markdown_text, :generate_toc).toc_content
     end
     
+    def h(to_escape)
+      CGI.escapeHTML(to_escape)
+    end
+    
     def to_relative(path)
     
       path = Pathname.new(path)
@@ -92,10 +102,13 @@ module Helper
     
       code_object = opts[:of] or raise Exception.new("Parameter :of (CodeObject) required")
       area        = opts[:in] or raise Exception.new("Parameter :in (Area) required")
+      exclude     = opts[:without] || []
     
       rendered = ""
     
-      token_groups = code_object.tokens.values.each do |tokens|        
+      tokens = code_object.tokens.reject {|token, v| exclude.include? token }
+    
+      token_groups = tokens.values.each do |tokens|        
            
         # tokens is an array of Token::Token
         if not tokens.empty? and tokens.first.area == area

data/lib/helper/linker.rb

@@ -75,15 +75,18 @@ module Helper
     
     # Returns the relative path (from dom) to this node
     # The Node can be either a {CodeObject::Base CodeObject} or a {Document::Document Document}.
+    #
+    # @note this method can be overwritten in every included Helper to fit your custom API-Layout
     # 
     # @param [CodeObject::Base, Document::Document] object
     #
     # @example 
-    #   Dom[:Foo][:bar].file_path #=> Foo/bar
+    #   Dom[:Foo][:bar].file_path                 #=> Foo/bar.html
+    #   Dom['Foo.bar'].file_path :format => :json #=> Foo/bar.json
     #   
     def path_to(object, args = {})
 
-      return "" if object.nil? 
+      return "" if object.nil?
       format = args[:format] || :html      
       path = object.parents.push(object).map{|p| p.name}.join('/') + ".#{format.to_s}"
     

data/lib/parser/parser.rb

@@ -73,8 +73,9 @@ module Parser
       
       
       # clean input and convert windows linebreaks to normal ones
-      @to_parse = input.gsub(/\r\n/, "\n")
+      @to_parse = input.force_encoding("UTF-8").gsub(/\r\n/, "\n")
       @scanner = StringScanner.new @to_parse
+    
       @comments = []
     end  
     
@@ -117,19 +118,32 @@ module Parser
     protected
     
     def parse_comment_until(ending)
-      content = @scanner.scan_until_ahead ending      
+      content = @scanner.scan_until_ahead ending     # this consumes ending, but don't includes it  
       comment = CommentParser.new(content).parse unless content.nil?  
            
       # only proceed, if it is a tokenized comment
-      return parse unless comment.has_tokens?  
+      return parse unless comment and comment.has_tokens?  
+      
+      
+      # First skip some white spaces, that may occure after comment
+      @scanner.skip /#{NO_BR}+/
       
       # search scope for that comment
       @scanner.skip /\n/
+      
       scope = @scanner.save_scanned { find_scope } 
-              
+      
+      
+      # FIX: UTF-8 characters destroyed the string-slicing, because scanner is working with 
+      # byte-positions only
+      @to_parse.force_encoding "ISO-8859-1"
+      
       code_line = @to_parse.line_of(scope.min) + @offset + 1
       source = @to_parse[scope]     
       
+      # Switch back to UTF-8
+      @to_parse.force_encoding "UTF-8"
+      
       # Add Metadata
       comment.add_meta_data @filepath, source, code_line   
       
@@ -147,7 +161,7 @@ module Parser
       end
       
       # adding |$ only if we don't ignore line_ends (which is most of the time)
-      @scanner.intelligent_skip_until /\{|\(|\}|\)#{'|$' unless ignore_line_end}/
+      @scanner.intelligent_skip_until /\{|\(|\}|\)#{"|$" unless ignore_line_end}/
       
       match = @scanner.matched
       
@@ -236,7 +250,7 @@ class StringScanner
   end
   
   def save_scanned
-    pos_start = self.pos #- 1 # fixes missing first char
+    pos_start = self.pos
     yield
     pos_end = self.pos
     Range.new(pos_start, pos_end)

data/lib/token/container.rb

@@ -1,6 +1,5 @@
 # ../data.img#1811394:1
 require_relative 'exceptions'
-require_relative 'handler'
 
 module Token
 

data/lib/token/handler.rb

@@ -67,23 +67,25 @@ 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) {
-          self.add_token tokenklass.new(:content => content)
+        tokenklass.new(:content => content)
       },
       
       :typed => ->(tokenklass, content) {
         typestring, content = TOKEN_W_TYPE.match(content).captures
         types = typestring.split /,\s*/
         
-        self.add_token tokenklass.new(:types => types, :content => content)
+        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*/
         
-        self.add_token tokenklass.new(:name => name, :types => types, :content => content)
+        tokenklass.new(:name => name, :types => types, :content => content)
       },
       
       :named_multiline => ->(tokenklass, content) { 
@@ -93,7 +95,28 @@ module Token
         name = rows.shift.strip
         content = rows.join("\n")
               
-        self.add_token tokenklass.new(:name => name, :content => content)
+        tokenklass.new(:name => name, :content => content)
+      },
+      
+      :named_nested_shorthand => ->(tokenklass, content) {
+          
+        # First remove linebreaks with 2-times intendation    
+        lines         = content.gsub(/\n((?!\n)\s){2}/, ' ').split(/\n/)
+        name          = lines.shift.strip
+        documentation = []
+        children      = []
+        
+        lines.each do |line|          
+          if TOKEN_W_TYPE_NAME.match(line)
+            # apply default-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
+            documentation << line
+          end
+        end
+      
+        tokenklass.new(:name => name, :types => [], :children => children, :content => documentation.join("\n"))   
       },
       
       :noop => ->(tokenklass, content) {}
@@ -107,6 +130,11 @@ module Token
       @@handlers
     end
     
+    # Use a default handler
+    def self.apply(default_handler, *args)
+      @@defaults[default_handler].call(*args)
+    end
+    
     # Registering a new Tokenhandler
     # ==============================
     # It is possible to register your own Tokenhandlers and therefore extend the
@@ -203,11 +231,11 @@ module Token
       if block_given?
         # handler is already defined
       elsif options[:handler] and @@defaults.include?(options[:handler])
-        handler = @@defaults[options[:handler]]
+        handler = self.build_handler(options[:handler])
       elsif options[:handler]
         raise Exception, "#{type} has no registered Tokenhandler"
       else
-        handler = @@defaults[:text_only]
+        handler = self.build_handler(:text_only)
       end      
       
       # Dynamically create Class named TokennameToken
@@ -237,6 +265,18 @@ module Token
     def self.add_default_handler(name, &block)
       @@defaults[name] = block;
     end
+    
+    protected
+    
+    def self.build_handler(type)
+      
+      handler =  @@defaults[type]
+    
+      ->(tokenklass, content) {
+        token = instance_exec(tokenklass, content, &handler)
+        self.add_token token unless token.nil? # can be NOOP
+      }
+    end
 
   end  
 end

data/lib/token/token.rb

@@ -15,7 +15,8 @@ module Token
     def self.process_options(options = {})
     
       # pushing defaults
-      options[:template] ||= :default
+      options[:template]    ||= :default
+      options[:description] ||= ""
       
       options[:html]     = { 
         :class => options[:token].to_s
@@ -23,7 +24,7 @@ module Token
       
       options[:area]     ||= :body      
     
-      %w(handler token template html area).each do |opt|        
+      %w(handler token template html area description).each do |opt|        
         self.class_variable_set("@@#{opt}".to_sym, options[opt.to_sym])      
         
         class_eval "

data/templates/helpers/template.rb

@@ -4,15 +4,25 @@ module Helper
   # need them anymore. 
   module Template
   
-    def signature(method)
-      params = method.params.map { |p|
+    def signature(method_or_token)
+    
+      if method_or_token.is_a? Token::Token
+        params = method_or_token.children.select {|t| t.token == :param }
+        returns = method_or_token.children.select {|t| t.token == :return }
+      else
+        params = method_or_token.params
+        returns = method_or_token.returns
+      end
+    
+    
+      params = params.map { |p|
         "<span class=\"param\">#{p.name}</span>" +
         "<span class=\"tooltip\">(<span class=\"types\">#{p.types.map{|t| link_to(t) }.join(', ')}</span>) " +
         "#{replace_links p.content}</span>"
-      }.join(', ') unless method.params.nil?
+      }.join(', ') unless params.nil?
       
-      return_types = method.returns.first.types.map{|type| link_to(type) }.join(', ') unless method.returns.nil? or method.returns.first.nil?
-      "(#{return_types || 'Void'}) <span class='name'>#{method.name}</span>(<span class='params'>#{params}</span>)"
+      return_types = returns.first.types.map{|type| link_to(type) }.join(', ') unless returns.nil? or returns.first.nil?
+      "(#{return_types || 'Void'}) <span class='name'>#{method_or_token.name}</span>(<span class='params'>#{params}</span>)"
     end
     
     def subsection(id, opts = {})

data/templates/resources/css/application.css

@@ -364,7 +364,8 @@ input:invalid, textarea:invalid {
       border-radius: 10px;
       padding: 0;
       margin: 0;
-      overflow-y: scroll; }
+      overflow: hidden;
+      /*overflow-y: scroll;*/ }
       #header .col50 section > ul::-webkit-scrollbar {
         width: 7px;
         height: 9px; }
@@ -498,6 +499,62 @@ input:invalid, textarea:invalid {
     font-family: "Consolas", "monospace";
     padding: 0 0.2em; }
 
+code.source, .syntaxhighlighter, code.example {
+  box-shadow: inset 0px 0px 0px 1px white;
+  border: 1px solid #d9d9d9;
+  font-family: "Consolas", "monospace";
+  display: block;
+  background: #f3f3f3;
+  font-size: 9pt;
+  line-height: 1.4em;
+  padding: 0.5em;
+  margin-bottom: 1.33em; }
+
+/* js-replaced version */
+.syntaxhighlighter {
+  /* revert no-js settings */
+  background: #fff;
+  padding: 0;
+  /* syntaxhighlighting settings */ }
+  .syntaxhighlighter table {
+    width: 100%; }
+    .syntaxhighlighter table td {
+      border: 1px solid #fff;
+      /* rebuild double-border effect */ }
+  .syntaxhighlighter .gutter {
+    background-color: #f3f3f3;
+    color: silver;
+    padding: 0.5em;
+    border-right: 1px solid #d9d9d9;
+    text-align: right; }
+    .syntaxhighlighter .gutter .line {
+      font-size: 9pt;
+      line-height: 1.4em; }
+  .syntaxhighlighter .code {
+    padding: 0.5em 0;
+    width: 100%; }
+    .syntaxhighlighter .code .line {
+      padding: 0 0.5em; }
+      .syntaxhighlighter .code .line:hover {
+        background: #f5f5f5; }
+  .syntaxhighlighter.example {
+    background: #f3f3f3; }
+    .syntaxhighlighter.example .line {
+      padding-left: 1em; }
+      .syntaxhighlighter.example .line:hover {
+        background: #efefef; }
+  .syntaxhighlighter .keyword {
+    font-weight: bold; }
+  .syntaxhighlighter .string {
+    color: #d84b0f; }
+  .syntaxhighlighter .comments {
+    color: #998;
+    font-style: italic; }
+  .syntaxhighlighter .comments a {
+    color: #998; }
+  .syntaxhighlighter .constants {
+    color: #4183c2; }
+
 body, select, input, textarea {
   font-family: Arial, sans-serif;
   font-size: 10pt;
@@ -539,13 +596,13 @@ a {
 .icon.prototype {
   background: url(../img/prototype.png) no-repeat left center;
   padding-left: 24px; }
-.icon.arrow_right, div#main .body .source.collapsed {
+.icon.arrow_right, div#main .body h3.source.collapsed {
   background: url(../img/arrow_right.png) no-repeat left center;
   padding-left: 24px; }
 .icon.arrow_up {
   background: url(../img/arrow_up.png) no-repeat left center;
   padding-left: 24px; }
-.icon.arrow_down, div#main .body .source {
+.icon.arrow_down, div#main .body h3.source {
   background: url(../img/arrow_down.png) no-repeat left center;
   padding-left: 24px; }
 
@@ -616,6 +673,7 @@ div#main nav.sidebar {
   box-shadow: inset 0px 0px 0px 1px white;
   border: 1px solid #d9d9d9;
   font-family: "Consolas", "monospace";
+  display: block;
   background: #f3f3f3;
   margin: 40px 0 12px 12px;
   padding: 0;
@@ -679,15 +737,6 @@ div#main .body .summary {
     div#main .body .summary a:hover {
       text-decoration: none;
       color: #3976b1; }
-div#main .body code.block {
-  box-shadow: inset 0px 0px 0px 1px white;
-  border: 1px solid #d9d9d9;
-  font-family: "Consolas", "monospace";
-  background: #f3f3f3;
-  display: block;
-  padding: 0.5em;
-  color: #555;
-  margin-bottom: 1.33em; }
 div#main .body .section {
   padding-bottom: 12px; }
 div#main .body .subsection > ul {
@@ -707,9 +756,9 @@ div#main .body .subsection h4 {
 div#main .body .subsection .types {
   font-family: "Consolas", "monospace";
   padding: 0 0.2em; }
-div#main .body .source {
+div#main .body h3.source {
   cursor: pointer; }
-  div#main .body .source.collapsed {
+  div#main .body h3.source.collapsed {
     border-bottom: 1px solid #d9d9d9;
     margin-bottom: 1.33em; }
 div#main .body .signature {
@@ -740,6 +789,8 @@ div#main .body .signature {
     padding: 0 0.2em; }
     div#main .body .signature .params .param {
       cursor: help; }
+div#main .body .overload {
+  margin-bottom: 3em; }
 
 div#main .notification {
   display: table; }

data/templates/resources/js/application.js

@@ -131,7 +131,7 @@ Module('Header', function(my) {
       // @section Filling private variables  
      
       my.apisearch = {
-        data: JSDOC.data.apisearch
+        data: J.data.apisearch
       };
       
       my.settings.apisearch = {
@@ -156,7 +156,7 @@ Module('Header', function(my) {
                 .hide()
                 .data(data)        
                 .append($('<a>', {
-                  href: JSDOC.root + data.path,
+                  href: J.root + data.path,
                   html: data.name
                 }));
         
@@ -291,20 +291,42 @@ Module('Body', function(my) {
   plugins: {
   
     source_code: function(my, reveal) {
-
+            
+      // apply syntax highlighting
+      SyntaxHighlighter.config.tagName = "code";      
+      SyntaxHighlighter.defaults.toolbar = false;
+                        
+      // replace all sources
       my.dom.find('h3.source').each(function(i, el) {
         
         var header = $(el).addClass('collapsed'),
-            code = header.next('code').hide();
+            code = header.next('code');
+       
+        SyntaxHighlighter.highlight(code.get(), {}, function(el) {
+          
+          var code = $(el).hide();
         
-        header.toggle(function(){
+          header.toggle(function(){
           header.removeClass('collapsed');
-          code.slideDown();
-        }, function() {      
-          code.slideUp(function() { header.addClass('collapsed'); });
+            code.slideDown();
+          }, function() {      
+            code.slideUp(function() { header.addClass('collapsed'); });
+          });
+        
         });
-      }); 
-    }  
+      });
+      
+      
+      // replace all code-examples
+      my.dom.find('code.example').each(function(i, el) {      
+        SyntaxHighlighter.highlight([el], {
+          gutter: false
+        }, function(el) {
+          $(el).find('.syntaxhighlighter').addClass('example');
+        });      
+      });
+      
+    }
   }
 });
 
@@ -315,4 +337,4 @@ $(function() {
     if(J.modules.hasOwnProperty(key))
       J.modules[key].init();
   }
-});
+});