docjs 0.1.4 → 0.1.5

data/docs/guides/TRY.md

@@ -0,0 +1,63 @@
+Installation
+============
+Prerequisites: You need Ruby >= 1.9 to run Doc.js
+
+    gem install docjs  
+
+After installing the gem, you can start by typing `docjs` in your console. This
+will bring up a small introduction and an overview of all available commands. 
+To retreive some more information about one specific command simply type 
+
+    docjs help COMMAND_NAME
+
+
+Basic Usage
+===========
+
+Configuration
+-------------
+Before you can use Doc.js you may create your own **Configuration-File**. This 
+can easily be done, using the built-in configuration-generator:
+
+    docjs configure
+    
+You optionally can specify the filename of your configuration file. If no file 
+is specified the configs will be written to `docjs.yml`.
+
+    docjs configure my_config_file.yml
+
+The configuration is an interactive one - simply answer the questions you will 
+be asked.
+
+
+Start documenting your code
+---------------------------
+To make jsdoc recognize your documentation you have to use some special tokens.
+Let's write a documented function `hello_doc`:
+    
+    /**
+     * @function hello_doc
+     *
+     * Innovative function to greet a Person.
+     *
+     * @param [String] name the person you want to greet
+     * @return void
+     */
+    function hello_doc(name) {
+      console.log("Hello " + name + "!");
+    }
+    
+The symbols `@function`, `@param` and `@return` are called **tokens** in Doc.js. 
+There are many more by default. To see which one you can use simply type:
+
+    docjs tokens
+  
+
+Run the documentation and enjoy!
+--------------------------------
+Now it's time to kickoff the documentation-process by typing:
+
+    docjs your_config.yml
+
+You will find the docs in the output-directory you have specified in your 
+config-file.

data/docs/guides/USE.md

@@ -0,0 +1,256 @@
+Configuration Options
+=====================
+You can run Doc.js with your custom configuration by either adding the desired
+options as **command-line** parameter or by writing them in a **configuration**-file.
+All available options are listed if you type:
+
+    docjs help docjs
+
+For example one may run docjs using only command-line options
+
+    docjs --files="js/*.js" --output="out" --appname="My Documentation"
+
+The same options, could be written in a config-file `docjs.yml`
+
+    files: 
+    - js/*.js
+    
+    output: out
+    appname: My Documentation
+    
+Then simply run:
+
+    docjs docjs.yml
+
+**Please note that all paths you specify will be resolved relative to the current working 
+directory!**
+
+
+List of Config-options
+----------------------
+
+| Option       | Default    | Usage            
+|--------------|------------|-----------------------------------------------------------------------
+| `appname`    | MyAppName  | The appname, which is stored in `Configs.options[:appname]` and can be used in the view-templates.
+| `docs`       | README.md  | List of Markdown-documents. You can use wildcards like `docs/**/*.md`
+| `files`      | ---        | List of JavaScript-Files. Just like the docs, you can use wildcards in the paths.
+| `logfile`    | ---        | Use this path if you want the log-messages to be written to a file.       
+| `loglevel`   | info       | All the messages lower then the specified level will not be printed. Available levels are (in that order): `debug`, `info`, `warn`, `error`
+|              |            | 
+| `output`     | out        | The generated documentation will be saved at this path. Please double-check it to prevent files to be overriden. 
+| `templates`  | *internal* | If you used `scaffold` or created your own templates by hand, you have to specify this path to make docjs use them.
+
+
+Note
+----
+Commandline lists like `docs` and `files` are whitespace separated.
+
+    --files="first_file.js" "others/*.js"
+    
+In a configuration file, you can use a simple YAML-list:
+
+    files: 
+    - first_file.js
+    - others/*.js
+
+
+Types
+=====
+Types specify the `type` of the documented CodeObject. There are a only a few types available per 
+default:
+
+- `@object`
+- `@function`
+- `@prototype`
+- (`@constructor`)
+
+The first two are considered primitives of the JavaScript language. Advanced concepts like classes, 
+mixins, pseudoclassical inheritence and so on can easily be added by 
+{file:CUSTOMIZE.md creating your own template} or modifying the existing one. `@prototype` is added
+as type, so you can see how to create your own custom-types. More information about the `@prototype`
+- type can be found in {file:PATTERNS.md#Prototypal_Inheritance the documentation-pattern-list}.
+
+Types classify the piece of code, you are documenting - so adding a type is essential and **always 
+required**.
+
+    /**
+     * @function sayHello
+     */
+
+Creates a documentation-element named `sayHello` with the type {CodeObject::Function}.
+
+Namespacing
+===========
+Because writing documentation takes enough time, there is a shorthand to express namespaces 
+**relative** to the parent in the surrounding scope. 
+
+    /**
+     * @object some.namespace
+     */
+    var some.namespace = {
+      
+      /**
+       * @function some.namespace.sayHello
+       */
+       sayHello: function() {...}
+    }
+
+can be rewritten as:
+
+    /**
+     * @object some.namespace
+     */
+    var some.namespace = {
+      
+      /**
+       * @function .sayHello
+       */
+       sayHello: function() {...}
+    }
+    
+This only works, because the JavaScript-Parser of Doc.js is working scope-aware. So you always can 
+use the dot-notation if your comment is in the lexical-scope of the parent comment.
+
+The dot-notation (`.sayHello`) was inspired by file-system, where one dot refers to the current
+directory. It also fit's into the JavaScript context, because the child can be accessed by using
+the dot.
+
+Please note: **If relative naming results in errors you still can use absolute naming**.
+
+Available Tokens
+================
+
+@author
+-------
+| Handler          | Area       | Template
+|:-----------------|:-----------|:-------------
+| :default         | :sidebar   | :default
+
+Can be used multiple times for many authors like:
+
+    @author Jon Foo
+    @author Peter Bar (Editor)
+    
+
+@constructor
+------------
+Simply creates a function-type and makes it answer `fun.constructor?` with `true`.
+
+
+@deprecated 
+-----------
+| Handler          | Area           | Template
+|:-----------------|:---------------|:-------------
+| :default         | :notification  | :default
+
+@event
+------
+| Handler                  | Area    | Template
+|:-------------------------|:--------|:-------------
+| :named_nested_shorthand  | :body   | :default
+
+@example
+--------
+| Handler          | Area   | Template
+|:-----------------|:-------|:-------------
+| :named_multiline | :body  | :example
+
+@function
+---------
+Type
+
+
+@method
+-------
+Type
+
+@note
+-----
+| Handler          | Area           | Template
+|:-----------------|:---------------|:-------------
+| :default         | :notification  | :default
+
+@object
+-------
+Using @object set's the type of the documented CodeObject to {CodeObject::Object}. No token will be
+added. See {file:USE.md#Types types} for further information about the types in Doc.js.
+
+@overload
+---------
+| Handler      | Area   | Template
+|:-------------|:-------|:----------
+| :custom      | :none  | :default
+
+You can use overloads, if your **function requires multiple signatures**.
+So instead of adding your `@param`'s and `@return`'s directly to the function's documentation you 
+specify overloads like:
+
+    /**
+     * @function non.sense
+     *
+     * @overload
+     *   Your description of this overload. Every line, not starting with `@` or intended by  2 
+     *   spaces (Which indicate linecontinuation) is treated as documentation for the overload.
+     *   
+     *   @param [String] name your name. We can continuate this line, by simply intending it
+     *     two spaces. You see? Simple, hu?
+     *   @param [Array<String>] collegues Your coworkers
+     *   @return [Void] Returns nothing!
+     *
+     * @overload
+     *   This is another way to use this function. It only requires one parameter.
+     *   @param [Object] person 
+     *   @return [String] The name of the person
+     */
+     
+Please note, that in line 7 of this example the continuation of @overload is achieved due intending
+the empty line with some spaces.
+
+
+@param
+------
+
+@private
+--------
+| Handler          | Area       | Template
+|:-----------------|:-----------|:-------------
+| :default         | :sidebar   | :default
+
+@prop
+-----
+
+@prototype
+----------
+
+@public
+-------
+| Handler          | Area       | Template
+|:-----------------|:-----------|:-------------
+| :default         | :sidebar   | :default
+
+@return
+-------
+
+@see
+----
+
+@throws
+-------
+
+@todo
+-----
+| Handler          | Area           | Template
+|:-----------------|:---------------|:-------------
+| :default         | :notification  | :default
+
+@version
+--------
+| Handler          | Area       | Template
+|:-----------------|:-----------|:-------------
+| :default         | :sidebar   | :default
+
+@warn
+-----
+| Handler          | Area           | Template
+|:-----------------|:---------------|:-------------
+| :default         | :notification  | :default

data/lib/boot.rb

@@ -7,7 +7,7 @@ require_relative 'logger'
 require_relative 'configs'
 require_relative 'parser/parser'
 require_relative 'token/handler'
-require_relative 'code_object/function'
+require_relative 'code_object/base'
 require_relative 'dom/dom'
 require_relative 'processor'
 
@@ -47,9 +47,5 @@ def load_templates(template_path = nil)
     template_path = File.absolute_path(template_path)
   end
   
-  require template_path + '/application.rb'
-  
-  # After loading all template files, we can include our default-template-helper
-  Tasks::RenderTask.use Helper::Template if Helper.const_defined? :Template
-   
+  require template_path + '/application.rb'   
 end

data/lib/code_object/base.rb

@@ -43,6 +43,11 @@ module CodeObject
     def docs=(docstring)
       @docs = docstring.strip
     end
+    
+    # can be overriden by subclasses
+    def display_name
+      @name
+    end
           
     protected
     

data/lib/dom/node.rb

@@ -128,7 +128,7 @@ module Dom
       path = path.split(NS_SEP_STRING)
       child = @children[path.shift.to_sym]
       
-      raise WrongPath.new(path) if child.nil?
+      return nil if child.nil?
       
       # decend recursive
       child[path.join(NS_SEP_STRING)]

data/lib/{tasks/render_task.rb → generator/generator.rb}

@@ -2,15 +2,18 @@ require_relative '../renderer'
 require_relative '../dom/dom'
 require_relative '../helper/helper'
 
-module Tasks
+module Generator
 
-  class RenderTask < Renderer
+  class Generator < Renderer
   
-    include Helper::Helper
-      
     def initialize
       super(Configs.templates + configs(:templates), configs(:layout))
       
+      # include all Helpers
+      Helper.constants
+            .map { |c| Helper.const_get c }
+            .each { |mod| extend mod if mod.is_a? Module }
+            
       # Set Global Context to Dom's root node
       @_context = Dom.root
     end
@@ -32,19 +35,22 @@ module Tasks
        configs(:description)
     end
     
+    # not neccesarily needed, because all Helpers are included by default
     def self.use(helper_module)
      include helper_module
-    end 
+    end
     
     def self.all
-      Tasks.constants
-           .map { |c| Tasks.const_get c }
-           .select { |klass| klass.class == Class and klass.superclass == Tasks::RenderTask }
+      # Otherwise we don't get the global Generator-Module
+      gen_module = Object.const_get(:Generator)
+      gen_module.constants
+                .map { |c| gen_module.const_get c }
+                .select { |klass| klass.class == Class and klass.superclass == self }
     end
     
     protected
     
-    # @group Task-Specification methods
+    # @group Generator-Specification methods
     
     def self.describe(desc)
       self.set_config(:description, desc.to_s)

data/lib/helper/helper.rb

@@ -4,12 +4,12 @@ require 'rdiscount'
 
 require_relative 'linker'
 
-# The Helpers are 'mixed' into your {Tasks::RenderTask} and therefore can be used in all 
+# 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 → Tasks::YourTask → Tasks::RenderTask → Renderer
+#     Helper::IncludedHelpers → Generator::YourGenerator → Generator::Generator → Renderer
 #
 # Somewhere at that chain you will find your desired function.
 module Helper

data/lib/helper/linker.rb

@@ -29,8 +29,7 @@ module Helper
       elsif target.is_a? CodeObject::Base
       
         if text.nil? and target.parent == context and context != Dom.root
-          text = ".#{target.name}"
-          text += "()" if target.is_a? CodeObject::Function
+          text = target.display_name
         elsif text.nil?
           text = target.qualified_name
         end
@@ -56,7 +55,11 @@ module Helper
       else        
         # use context dependent resolving functionality as specified in {Tasks::RenderTask}
         obj = resolve target
-        to_relative path_to obj unless obj.nil?  
+        unless obj.nil?
+          to_relative path_to obj
+        else
+          nil
+        end  
       end
         
       text ||= target 
@@ -120,14 +123,5 @@ module Helper
         link_to(name, title)
       end
     end
-    
-    def link_on_page(object)
-      if object.is_a? CodeObject::Function
-         link_to "#method-#{object.name}", ".#{object.name}()"
-      else
-        link_to "#object-#{object.name}", ".#{object.name}"
-      end
-    end
-  end
-  
+  end  
 end