docjs 0.1.5 → 0.2

data/lib/helper/linker.rb

@@ -10,13 +10,31 @@ module Helper
     HASH = /^#\S*/
     DOCUMENTATION = /^doc\:([^\s#]+)(#\S+)?/
 
-    # @note link_to - first argument can be
-    #   "file:some/path/to_a.file"
-    #   "Code.object.path"
-    #   ".relative.code_object.path"
-    #   "http://external.address.com"
-    #   instance_of_code_object
+    # link to can link many types of resources, the `target` can be one of:
+    # 
+    # - `"file:some/path/to_a.file"`
+    # - `"doc:Document.path"`
+    # - `"Code.object.path"`
+    # - `".relative.code_object.path"`
+    # - `"http://external.address.com"`
+    # - `"mailto:me@example.com"`
+    # - `instance_of_code_object`
+    # - `instance_of_a_doc_object`
+    # 
+    # Most of the time it will be used by {#replace_links} to automatically convert links in 
+    # documentation like `{Core.some.object see some.object}`
     #
+    # @example
+    #   link_to "doc:README", "see readme"
+    #   link_to Dom.docs[:README], "see readme"
+    # 
+    #   link_to "file:pdf/information.pdf", "pdf-file (1.5MB)"
+    #   link_to "http://b-studios.de", "b-studios"
+    # 
+    # @param [String, Document::Document, CodeObject::Base] target for further information see above
+    # @param [String] text the link text
+    # @return [String] a html-link
+    # @param [Hash] args the arguments, which will be reached through to {Helper#tag}
     def link_to(target, text = nil, args = {})
            
       Logger.debug "Trying to link #{target}"
@@ -68,10 +86,19 @@ module Helper
         Logger.warn "Could not resolve link to '#{target}'"
         return text 
       end
-     
-      tag :a, text, :href => link      
+      
+      tag :a, text, args.merge({ :href => link })      
     end
     
+    # Creates a link, relative to the current output-path
+    #
+    # @example
+    #   relative_link '/home/me/output/test.html', 'Click me'
+    #   #=> "<a href='../test.html'>Click me</a>"
+    #
+    # @param [String] path absolute path to the resource
+    # @param [String] text the link text
+    # @return [String] html-link
     def relative_link(path, text)
       tag :a, text, :href => to_relative(path)
     end
@@ -104,8 +131,17 @@ module Helper
         object.to_s
       end   
     end
-
-    # (see https://github.com/lsegal/yard/blob/master/lib/yard/templates/helpers/html_helper.rb)
+    
+    # finds any links, that look like `{my_link}` and replaces them with the help of {#link_to}
+    #
+    # @example
+    #   replace_links "This is a text, containing a {some.reference link}"
+    #   #=> "This is a text, containing a <a href='../some/reference.html'>link</a>"
+    #
+    # @param [String] text
+    # @return [String] text containing html-links
+    #
+    # @see https://github.com/lsegal/yard/blob/master/lib/yard/templates/helpers/html_helper.rb#L170
     def replace_links(text)
       code_tags = 0
       text.gsub(/<(\/)?(pre|code|tt)|(\\)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W<]|.+<\/|$)/m) do |str|
@@ -124,4 +160,4 @@ module Helper
       end
     end
   end  
-end
+end

data/lib/parser/comment.rb

@@ -3,22 +3,22 @@ require_relative '../code_object/converter'
 
 module Parser
 
-  # Together with {Parser::Coment} it acts as an **Interface** between {Parser} 
-  # and {CodeObject}. Parser::Comment creates instances of Tokenline, which are
-  # then analysed by {Token::Container#process_token} 
+  # Together with {Parser::Coment} it acts as an **Interface** between {Parser} and {CodeObject}. 
+  # Parser::Comment creates instances of Tokenline, which are then analysed by 
+  # {Token::Container#process_token} 
   #
   # @see Parser::Comment
   # @see Parser::CommentParser
   Tokenline = Struct.new :token, :content
   
   # Comment contains all **tokenlines** and **doclines**, which are created by the
-  # {Parser::Parser parser}. The tokenlines are stored as {Tokenline}. Because
-  # of this Comment and Tokenline act as **Interface** for {CodeObject::Base}.
+  # {Parser::Parser parser}. The tokenlines are stored as {Tokenline}. Because of this Comment and 
+  # Tokenline act as **Interface** for {CodeObject::Base}.
   #
-  # The tokens will further be processed by {Token::Container}, which 
-  # is mixed in to CodeObject::Base).
+  # The tokens will further be processed by {Token::Container}, which is mixed in to 
+  # {CodeObject::Base}).
   #
-  # @example creating of an comment
+  # @example creating an comment
   #   c = Parser::Comment.new "the original string of the comment, with all tokens and doclines"
   #   c.add_tokenline :param "[String] first_parameter this is the description for param1"
   #   c.add_docline "Some documentation of the comment"
@@ -56,6 +56,7 @@ module Parser
       @children += comments
     end
     
+    # @return [Boolean]    
     def has_tokens?
       not @tokenlines.empty?
     end    

data/lib/parser/comment_parser.rb

@@ -9,9 +9,8 @@ module Parser
       @comment = Comment.new(input)
     end
 
-    # All lines, that start with a `@-symbol` will be processed as tokenline
-    # if the next line after a token starts with two spaces, it will be 
-    # interpreted as continuation of the preceding token.
+    # All lines, that start with a `@-symbol` will be processed as tokenline. If the next line after 
+    # a token starts with two spaces, it will be interpreted as continuation of the preceding token.
     #
     # @example multiline token
     #   @multiline_token this is a multi_line token, it won't
@@ -19,8 +18,8 @@ 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] Creates an instance of {Parser::Comment} and attaches all find doc- 
+    #   and tokenlines to it.
     def parse
       # we don't want the linebreak of the comment start in our first docline
       # i.e. ignore '/**\n' 
@@ -34,8 +33,8 @@ module Parser
     
     protected
     
-    # skips leading spaces with asterisk aka {Parser::LINE_START LINE_START}
-    # then checks for {Parser::TOKENLINE_START @-symbol} to parse a token
+    # skips leading spaces with asterisk aka {Parser::LINE_START LINE_START} then checks for 
+    # {Parser::TOKENLINE_START @-symbol} to parse a token
     def parse_comment_line
       self.skip LINE_START
       
@@ -59,9 +58,9 @@ module Parser
     #     @token_two some text, and some more
     #       and even some more.
     #
-    #   1. Scan til the first linebreak (or end of string, if it reaches it first)
-    #   2. Check if next line starts with two spaces, skip them
-    #   3. Parse recursivly til the next line does not start with two spaces
+    # 1. Scan til the first linebreak (or end of string, if it reaches it first)
+    # 2. Check if next line starts with two spaces, skip them
+    # 3. Parse recursivly til the next line does not start with two spaces
     #
     # @see StringScanner.scan_until_ahead to see another example
     #   of the positive lookahead

data/lib/parser/parser.rb

@@ -58,8 +58,7 @@ module Parser
   
     attr_reader :filepath, :offset
   
-    # A new StringScanner instance will be used to {#parse parse} the given
-    # `input`.
+    # A new StringScanner instance will be used to {#parse parse} the given `input`.
     #
     # @param [String] input
     def initialize(input, args = {})
@@ -79,8 +78,8 @@ module Parser
     end  
     
     
-    # Recursivly parses the {#initialize given input} and thereby ignores
-    # strings.
+    # Recursivly parses the {#initialize given input} and thereby ignores strings.
+    #
     # @todo Rewrite to use skip_intelligent_until
     # @return [Array<Parser::Comment>] the parsed comment-stream
     def parse()
@@ -220,8 +219,7 @@ class StringScanner
     return content
   end
   
-  # will stop to scan at the specified pattern or at eos and returns the
-  # consumed string.
+  # will stop to scan at the specified pattern or at eos and returns the consumed string.
   # 
   # @param [Regexp] pattern the pattern to scan for
   # @return [String] the String before `pattern`

data/lib/processor.rb

@@ -46,7 +46,7 @@ module Processor
     comments.each do |comment|    
       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)     # add to dom
+      Dom.add_node(code_object.path, code_object) unless code_object.nil?     # add to dom
     end
   end
   

data/lib/token/handler.rb

@@ -240,6 +240,11 @@ module Token
     } 
     @@handlers = {}    
     
+    # Hash for all registered CodeObject-Types. 
+    # For example: 
+    #     { :function => CodeObject::Function }
+    @@types = {}
+    
     # Attribute-Reader for all registered `@@handlers`
     #
     # @return [Hash<Symbol, Block>]
@@ -247,6 +252,12 @@ module Token
       @@handlers
     end
     
+    # @return [Hash<Symbol, CodeObject::Base> with symbol beeing the token and CodeObject::Base any
+    #   subclass
+    def self.types
+      @@types
+    end
+    
     # Use a default handler
     def self.apply(default_handler, *args)
       @@defaults[default_handler].call(*args)
@@ -321,6 +332,8 @@ module Token
       
       });  
       
+      
+      @@types[tokenname] = options[:type] unless options[:type].nil?      
       @@handlers[tokenname] = klass
     end
     

data/lib/token/token.rb

@@ -1,7 +1,6 @@
 module Token
 
-  # Serves as Base-Class for all registered tokens.
-  # Registering a token with 
+  # Serves as Base-Class for all registered tokens. Registering a token with 
   #     
   #     Token:Handler.register :awesome, :template => :foo, :description => "Description"
   #
@@ -28,8 +27,8 @@ module Token
     #
     #     Token:Handler.register :awesome, :template => :foo, :description => "Description"
     # 
-    # This will create a class Token::AwesomeToken, which extends {Token::Token}. After creating the class
-    # {.process_options} will be called with all provided options to apply those to the class.
+    # This will create a class Token::AwesomeToken, which extends {Token::Token}. After creating the 
+    # class {.process_options} will be called with all provided options to apply those to the class.
     #
     # Because the options are valid for all instances of a tokenclass, the contents are stored in 
     # class-variables and class-methods are defined as accessors:

data/templates/generators/api_pages_generator.rb

@@ -2,8 +2,6 @@ module Generator
 
   class ApiPagesGenerator < Generator
 
-    # @todo those methods and therefore all class-variables @@configs are shared with all inheriting
-    #   classes. i.e. The last change will be applied to all
     describe     'renders documented objects type-dependant (Functions and Objects)'
     layout       'application'
     
@@ -23,7 +21,6 @@ module Generator
       end
     end
 
-    # @todo switch on registered Types to enable dynamic view-changing
     def render_object(code_object)       
     
       Logger.info "Rendering CodeObject '#{code_object.name}'"
@@ -32,7 +29,6 @@ module Generator
         @object = code_object
         @methods = @object.children.values.select {|c| c.is_a? CodeObject::Function }
         @children = @object.children.values - @methods
-        # Render has to be documented very well, because it will be used in RenderTasks
         render 'object/index', :to_file => path_to(code_object, :format => :html)
       end
     end

data/templates/generators/docs_generator.rb

@@ -14,8 +14,7 @@ module Generator
         next if doc.is_a? Dom::NoDoc 
                
         render_document doc        
-      end
-      
+      end      
       
       readme = Dom.docs.find('README')
       in_context readme do

data/templates/resources/css/application.css

@@ -292,7 +292,12 @@ input:invalid, textarea:invalid {
       display: block;
       float: right; }
     #header nav input#search {
+      -moz-border-radius: 10px;
+      /* Firefox */
+      -webkit-border-radius: 10px;
+      /* Safari, Chrome */
       border-radius: 10px;
+      /* CSS3 */
       outline: none;
       padding: 0.2em 0.5em; }
     #header nav #page-menu {
@@ -305,9 +310,19 @@ input:invalid, textarea:invalid {
         float: left;
         /* rounded corners */ }
         #header nav #page-menu li:first-child a {
-          border-radius: 0 0 0 10px; }
+          -moz-border-radius: 0 0 0 10px;
+          /* Firefox */
+          -webkit-border-radius: 0 0 0 10px;
+          /* Safari, Chrome */
+          border-radius: 0 0 0 10px;
+          /* CSS3 */ }
         #header nav #page-menu li:last-child a {
-          border-radius: 0 0 10px 0; }
+          -moz-border-radius: 0 0 10px 0;
+          /* Firefox */
+          -webkit-border-radius: 0 0 10px 0;
+          /* Safari, Chrome */
+          border-radius: 0 0 10px 0;
+          /* CSS3 */ }
       #header nav #page-menu a {
         background: #4a8fd3;
         /* Old browsers */
@@ -360,8 +375,13 @@ input:invalid, textarea:invalid {
       padding: 0 0 0 0.5em;
       margin-bottom: 0.5em; }
     #header .col50 section > ul {
-      border: 1px solid #eee;
+      -moz-border-radius: 10px;
+      /* Firefox */
+      -webkit-border-radius: 10px;
+      /* Safari, Chrome */
       border-radius: 10px;
+      /* CSS3 */
+      border: 1px solid #eee;
       padding: 0;
       margin: 0;
       overflow: hidden;
@@ -483,6 +503,12 @@ input:invalid, textarea:invalid {
   /* W3C */
   font-family: Arial, sans-serif;
   font-size: 10pt;
+  -moz-border-radius: 5px;
+  /* Firefox */
+  -webkit-border-radius: 5px;
+  /* Safari, Chrome */
+  border-radius: 5px;
+  /* CSS3 */
   display: none;
   position: absolute;
   padding: 0.5em;
@@ -491,7 +517,6 @@ input:invalid, textarea:invalid {
   font-size: 9pt;
   color: #eee;
   border: 1px solid #fff;
-  border-radius: 5px;
   box-shadow: 0 0 10px rgba(0, 0, 0, 0.15); }
   .tooltip a {
     color: #8eb5db; }
@@ -506,7 +531,7 @@ code.source, .syntaxhighlighter, code.example {
   display: block;
   background: #f3f3f3;
   font-size: 9pt;
-  line-height: 1.4em;
+  line-height: 1.6em;
   padding: 0.5em;
   margin-bottom: 1.33em; }
 
@@ -528,12 +553,12 @@ code.source, .syntaxhighlighter, code.example {
     border-right: 1px solid #d9d9d9;
     text-align: right; }
     .syntaxhighlighter .gutter .line {
-      font-size: 9pt;
-      line-height: 1.4em; }
+      height: 1.6em; }
   .syntaxhighlighter .code {
     padding: 0.5em 0;
     width: 100%; }
     .syntaxhighlighter .code .line {
+      height: 1.6em;
       padding: 0 0.5em; }
       .syntaxhighlighter .code .line:hover {
         background: #f5f5f5; }
@@ -634,8 +659,13 @@ div#main {
   max-width: 1000px;
   display: block;
   overflow: hidden;
-  margin-top: -20px;
+  -moz-border-radius: 10px 10px 0 0;
+  /* Firefox */
+  -webkit-border-radius: 10px 10px 0 0;
+  /* Safari, Chrome */
   border-radius: 10px 10px 0 0;
+  /* CSS3 */
+  margin-top: -20px;
   box-shadow: 0px 0px 5px rgba(0, 0, 0, 0.1);
   border-top: 1px solid #eee; }
   div#main h1 {
@@ -656,11 +686,16 @@ div#main {
     padding-right: 20px; }
   div#main header h1 .flag {
     font-family: "Consolas", "monospace";
+    -moz-border-radius: 5px;
+    /* Firefox */
+    -webkit-border-radius: 5px;
+    /* Safari, Chrome */
+    border-radius: 5px;
+    /* CSS3 */
     display: block;
     background: #fcded1;
     border: 1px solid #f9c2ab;
     color: #5490c8;
-    border-radius: 5px;
     padding: 0.4em 1em;
     display: block;
     float: right;
@@ -675,9 +710,14 @@ div#main nav.sidebar {
   font-family: "Consolas", "monospace";
   display: block;
   background: #f3f3f3;
+  -moz-border-radius: 5px;
+  /* Firefox */
+  -webkit-border-radius: 5px;
+  /* Safari, Chrome */
+  border-radius: 5px;
+  /* CSS3 */
   margin: 40px 0 12px 12px;
   padding: 0;
-  border-radius: 5px;
   font-size: 8pt;
   color: #999; }
   div#main nav.sidebar > * {
@@ -727,11 +767,16 @@ div#main .body .summary {
     float: left; }
   div#main .body .summary a {
     font-family: "Consolas", "monospace";
+    -moz-border-radius: 5px;
+    /* Firefox */
+    -webkit-border-radius: 5px;
+    /* Safari, Chrome */
+    border-radius: 5px;
+    /* CSS3 */
     display: block;
     background: #eff4fa;
     border: 1px solid #d0e0f0;
     color: #5490c8;
-    border-radius: 5px;
     padding: 0.4em 1em;
     margin: 0.25em; }
     div#main .body .summary a:hover {
@@ -763,11 +808,16 @@ div#main .body h3.source {
     margin-bottom: 1.33em; }
 div#main .body .signature {
   font-family: "Consolas", "monospace";
+  -moz-border-radius: 5px;
+  /* Firefox */
+  -webkit-border-radius: 5px;
+  /* Safari, Chrome */
+  border-radius: 5px;
+  /* CSS3 */
   display: block;
   background: #eff4fa;
   border: 1px solid #d0e0f0;
   color: #5490c8;
-  border-radius: 5px;
   padding: 0.4em 1em;
   color: #000;
   font-size: 12pt;
@@ -775,11 +825,16 @@ div#main .body .signature {
   margin-bottom: 1.33em; }
   div#main .body .signature.constructor {
     font-family: "Consolas", "monospace";
+    -moz-border-radius: 5px;
+    /* Firefox */
+    -webkit-border-radius: 5px;
+    /* Safari, Chrome */
+    border-radius: 5px;
+    /* CSS3 */
     display: block;
     background: #fcded1;
     border: 1px solid #f9c2ab;
     color: #5490c8;
-    border-radius: 5px;
     padding: 0.4em 1em;
     color: #000; }
   div#main .body .signature .name {
@@ -795,33 +850,53 @@ div#main .body .overload {
 div#main .notification {
   display: table; }
   div#main .notification section {
+    -moz-border-radius: 5px;
+    /* Firefox */
+    -webkit-border-radius: 5px;
+    /* Safari, Chrome */
+    border-radius: 5px;
+    /* CSS3 */
     display: block;
     background: #f3f3f3;
     border: 1px solid #dfdfdf;
     color: #666666;
-    border-radius: 5px;
     padding: 0.4em 1em;
     margin-bottom: 0.5em; }
     div#main .notification section.deprecated {
+      -moz-border-radius: 5px;
+      /* Firefox */
+      -webkit-border-radius: 5px;
+      /* Safari, Chrome */
+      border-radius: 5px;
+      /* CSS3 */
       display: block;
       background: #cccccc;
       border: 1px solid #b8b8b8;
       color: #666666;
-      border-radius: 5px;
       padding: 0.4em 1em; }
     div#main .notification section.todo {
+      -moz-border-radius: 5px;
+      /* Firefox */
+      -webkit-border-radius: 5px;
+      /* Safari, Chrome */
+      border-radius: 5px;
+      /* CSS3 */
       display: block;
       background: #fef377;
       border: 1px solid #feef4e;
       color: #4e4e07;
-      border-radius: 5px;
       padding: 0.4em 1em; }
     div#main .notification section.warn {
+      -moz-border-radius: 5px;
+      /* Firefox */
+      -webkit-border-radius: 5px;
+      /* Safari, Chrome */
+      border-radius: 5px;
+      /* CSS3 */
       display: block;
       background: #ff5544;
       border: 1px solid #ff301b;
       color: #4e1a07;
-      border-radius: 5px;
       padding: 0.4em 1em; }
     div#main .notification section ul {
       list-style: none;