docjs 0.1

data/CONCEPT.md

@@ -0,0 +1,80 @@
+Concept of the Documententation
+===============================
+
+There are only two build-in types, we want to pay attention to:
+
+  1. Objects
+  2. Functions
+  
+  
+Object
+------
+By **Objects** we mean all kind of *things*, that can contain other things. Those containted ones, we call **properties** of the Object.
+
+In JavaScript this may look like:
+
+    var obj = {
+      property_one: function() { ... },
+      property_two: {
+        // another object
+      },
+      property_three: 3
+    }
+
+
+Function
+--------
+**Functions** are *things*, that can be executed. They can have **parameters** and **return-values** There are two types of Functions: plain functions and **constructors**.
+
+Example for a plain function:
+
+    function my_func(param) {
+      return "Hello world!";
+    }
+
+Example for a function as a constructor
+
+    function my_constructor() {
+      this.message = "Hello world!";    
+    }
+
+
+  Remember: any return-value of a constructor-function will be ignored and replaced by this
+
+But a function can be an object at the same time. For example:
+
+    function my_func_two() {
+      return "fancy function";    
+    }
+    my_func_two.message = "Say hello to Mr. Foo";
+
+Most important a function can contain one special property **prototype**.
+
+  Remember: In this case the function has to be a constructor. Otherwise prototype would be useless, because it is only used when creating instances of the function using new. After creating an instance the prototype-object is accessible in the this-context of the instance.
+
+    function my_constructor() {
+      this.message = "Hello world!";    
+    }
+    my_constructor.prop1 = 456;
+    my_constructor.prototype = {
+      some_proto_prop: 123
+    }
+
+Revealing Module Pattern
+------------------------
+But what about revealing modules?
+
+    function my_module() {
+
+      // some private stuff here
+
+      return {
+        property_of_the: "returned object"
+      };    
+    }
+
+One should pay attention to this pattern while creating a documentation tool.
+
+Conclusion
+----------
+So we can break it down to Functions and Objects. Objects can have properties. Functions can, at the same time, be Objects. There are special functions, called *constructors*, which in turn have one special property called *prototype*. This property has to be handled special in documentation.

data/DOCUMENTATION.md

@@ -0,0 +1,41 @@
+Fullqualifier
+-------------
+Like an absolute path (/etc/init.d/apache2) we use `FOO.bar` as fullqualifier to
+an object or function.
+
+A leading dot suggests filling the empty leading space with the current parsing-context
+without modifying it. As such `.something_else` would be resolved to 
+`FOO.bar.something_else` in the current context.
+
+Examplecode:
+
+    /**
+     * @function my_module
+     * @return [my_module.object]
+     */
+    function my_module() {
+
+      // some private stuff here
+      
+      
+      /** 
+       * @property .foo
+       */
+      my_module.foo = 123;
+
+
+      /** 
+       * @property .foo_bar
+       */
+      my_module.foo_bar = 789;
+      
+
+      /**
+       * @object .object
+       */
+      return {
+        /* @property .object.property_of_the */
+        property_of_the: "returned object"
+      };    
+    }
+

data/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (C) 2011 by Jonathan Brachthäuser (http://b-studios.de)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,19 @@
+jsdoc
+=====
+After total dataloss i have to rewrite the Readme's and Test's, so please be patient.
+jsdoc is currently **not a bit** stable. Stay tuned.
+
+For some more information about the architecture see:
+
+  - {Parser}  
+  - {CodeObject}
+  - {Token}
+  - {Dom}  
+  - {Renderer}
+  
+The 'executable' is {JsDoc}
+
+Required Gems
+=============
+  - thor
+  - rdiscount

data/RENDERING.md

@@ -0,0 +1,8 @@
+Es bietet sich an für manche Objekte eine extra Seite anzulegen und für andere nicht.
+Stellt sich nur die Frage, wo man diese Grenze zieht.
+
+Derzeit gibt es:
+  - Objekte ({CodeObject::Object})
+  - Funktionen ({CodeObject::Function})
+  
+Beide können selbst wieder andere Objekte und Funktionen beinhalten.

data/bin/docjs

@@ -0,0 +1,190 @@
+#!/usr/bin/ruby1.9
+# We need pathname to make it work with sym-links
+require 'pathname' 
+require Pathname.new(__FILE__).realpath + '../../lib/boot'
+
+# @todo The general flow of information should be documented here
+# 
+# --String--> [Parser] --Commentstream--> [CodeObjectFactory] --Objectstream--> [Registry]
+#
+# Parser
+# ------
+# Turns the incoming stream of characters (string) into a stream of 
+# {Parser::Comment comments}. Those comments contain the parsed doclines, which
+# are simply all lines found in the comment and all tokenlines. 
+
+# configure approot
+Configs.set :root  => Pathname.new(__FILE__).realpath + '../..'
+
+# Pipeline:
+#   1. load options from shell and specified YAML-file (if any)
+#   2. load files
+#   3. parse files
+#   4. turn into objects and save to dom
+#   5. render templates
+#
+# @note options declared in a build.yml will override command-line ones
+# @todo command line option to copy all templates to specified directory like
+#   jsdoc dump_templates ../templates/original
+class JsDoc < Thor
+    
+  include Thor::Actions
+    
+  desc "jsdoc CONFIG_FILE", "Starts documentation process"
+  set_options :files =>
+                  { :type => :array,  :aliases => '-f', :default => [], :required => true },
+               
+              :docs =>
+                  { :type => :array,  :aliases => '-d', :default => ['README.md'], :required => true },
+  
+              :output =>
+                  { :type => :string, :aliases => '-o', :default => 'out' },
+                  
+              :templates =>
+                  { :type => :string, :aliases => '-t', :default => Configs.root + 'templates' },
+                  
+              :appname =>
+                  { :type => :string, :aliases => '-n', :default => "MyAppName" },
+                  
+              :logfile =>
+                  { :type => :string, :aliases => '-lf', :default => 'jsdoc.log' },
+                  
+              :loglevel =>
+                  { :type => :string, :aliases => '-ll', :default => 'info' }
+  
+  def jsdoc(config_file = nil)
+    # @see Thor#merge_options
+    configs = config_file ? merge_options(options, config_file) : options
+    
+    begin
+      setup_application configs
+      
+      # load application specific files
+      require Configs.templates + '/application.rb'
+      
+      # Config Thor settings
+      JsDoc.source_root(Configs.templates)
+      self.destination_root = Configs.output
+      
+      Processor.prepare_documents
+      # let's check our Documents tree
+      Dom.docs.print_tree
+      
+      # the configs are now available through our Configs-module      
+      Processor.process_and_render
+        
+      Logger.info "Copying template resources to output"
+      directory 'resources/img', './img' # copy resources
+      directory 'resources/css', './css'
+      directory 'resources/js', './js'
+            
+    rescue Exception => error
+      Logger.error error.message + "\n" + error.backtrace.map{|l| "  #{l}" }.join("\n")
+    end    
+  end  
+    
+    
+    
+  desc "tokens", "Lists all supported tokens"
+  def tokens
+    say "Supported tokens:"
+    say Token::Handler.handlers.map{|k,v| "  @#{k}" }.sort.join "\n"    
+  end
+  
+  
+  
+  desc "tasks", "Lists all registered render-tasks"
+  def tasks
+    say "Registered render-tasks:"
+    
+    task_table = Processor.render_tasks.map{|k,v| [":#{k}","# #{v.description}"] }.sort
+    
+    print_table task_table, :ident => 2, :colwidth => 20    
+  end  
+  
+  
+  
+  # @todo implement!
+  desc "scaffold OUTPUT_DIR", "You can use scaffolding to get the templates and some basic ruby-files, that you will need to create your own templates"
+  set_options :logfile =>
+                  { :type => :string, :aliases => '-lf', :default => 'jsdoc.log' },
+                  
+              :loglevel =>
+                  { :type => :string, :aliases => '-ll', :default => 'info' }
+  def scaffold(output_dir)
+      
+    setup_application options.merge({
+      :output => output_dir,
+      :templates => output_dir
+    })
+    
+    # Setup Thor paths
+    JsDoc.source_root(Configs.root)
+    self.destination_root = Configs.output
+    Configs.set(:scaffolding_path, output_dir)
+    
+    
+    answers = {}    
+    yes_no = "(y|n)"
+    
+    Logger.info "We need some information from you, to customize the scaffolding process to your needs."
+    
+    answers[:build] = yes? "Do you wan't to generate a build.yml? #{yes_no}"
+    write_build_file if answers[:build]
+    
+    Configs.set :answers, answers
+        
+    # Work with the answers    
+    Logger.info "Copying the template files to #{Configs.templates}"
+    directory 'templates', Configs.templates    # copy templates and resources
+        
+    Logger.info "Copying the included *.rb files to #{Configs.includes}"    
+  end
+  
+  
+  protected
+  
+  def write_build_file
+  
+    build = {
+      'files'     => [],
+      'docs'      => [],
+      'output'    => 'docs',
+      'logfile'   => 'logfile.log',
+      'loglevel'  => 'info',
+      'templates' => Configs.scaffolding_path
+    }
+    
+    say "\nPlease enter the name of your App", :bold
+    build['appname'] = ask ">"
+  
+    say "\nPlease enter the javascript-files you want to integrate into your documentation", :bold
+    say "(You will be asked multiple times, unless your answer is empty) You also can specify a file-matching pattern, foo/**/*.js"
+    
+    while true do
+      answer = ask ">"
+      break if answer == ""
+      build['files'] << answer
+    end
+    
+    say "\nPlease enter the markdown-documentation-files you want to integrate into your documentation", :bold
+    say "(You will be asked multiple times, unless your answer is empty) You also can specify a file-matching pattern, like docs/*.md"
+    
+    while true do
+      answer = ask ">"
+      break if answer == ""
+      build['docs'] << answer
+    end
+    
+    # answers[:scss_build] = yes? "Do you wan't to integrate SCSS into your build-process? #{yes_no}"
+    
+    # maybe ask some more information to generate build.yml
+    create_file Configs.wdir + "/build.yml", build.to_yaml
+  end
+  
+end
+
+unless ARGV.first and JsDoc.method_defined?(ARGV.first)
+  ARGV.unshift 'jsdoc'
+end
+JsDoc.start(ARGV)

data/docjs.gemspec

@@ -0,0 +1,32 @@
+Gem::Specification.new do |s|
+  s.required_rubygems_version = ">= 1.5"
+  s.required_ruby_version = '>= 1.9'
+
+
+  s.name = 'docjs'
+  s.version = '0.1'
+  s.date = '2011-06-07'
+  s.summary = "Javascript Documentation Generator"
+  s.description = "Create beautyful Javascript documentations with this ruby-gem. It's pretty easy to customize and add your own tokens/DSL."
+  s.homepage = "https://github.com/b-studios/docjs"
+  s.authors = ["Jonathan Brachthäuser"]
+  s.email = "jonathan@b-studios.de"
+  s.rubyforge_project = s.name
+
+  s.files = `git ls-files`.split("\n").find_all do |file|
+    file !~ /^yard$/ && 
+    file !~ /^run_tests$/ &&
+    file !~/^build/ &&
+    file !~/gitignore/
+  end
+  
+  s.test_files    = `git ls-files -- {test}/*`.split("\n")
+
+  s.executables = ['docjs']
+  s.default_executable = 'bin/docjs'
+  
+  s.add_dependency 'rdiscount'
+  s.add_dependency 'thor'
+
+  s.require_path = 'lib'
+end

data/lib/boot.rb

@@ -0,0 +1,34 @@
+require 'thor'
+require 'json'
+require 'yaml'
+
+require_relative 'thor'
+require_relative 'logger'
+require_relative 'configs'
+require_relative 'parser/parser'
+require_relative 'code_object/function'
+require_relative 'dom/dom'
+require_relative 'processor'
+
+def setup_application(options)
+        
+  # initialize Logger
+  Logger.setup :logfile => File.expand_path(options[:logfile], Dir.pwd),
+               :level   => (options[:loglevel]).to_sym
+  
+  Logger.info "Setting up Application"
+  
+  # Process option-values and store them in our Configs-object
+  Configs.set :options      => options, # Just store the options for now
+              :wdir         => Dir.pwd, # The current working directory
+              :output       => File.absolute_path(options[:output]),
+              :templates    => File.absolute_path(options[:templates]),
+              :includes     => (options[:includes] && File.absolute_path(options[:includes])),
+              :files        => (options[:files] && options[:files].map {|path| Dir.glob(path) }.flatten),
+              :docs         => (options[:docs] && options[:docs].map {|path| Dir.glob(path) }.flatten)
+  
+  Logger.debug "Given options: #{options}"
+  Logger.debug "App Root:      #{Configs.root}"
+  Logger.debug "Working Dir:   #{Configs.wdir}"
+  Logger.debug "Output Dir:    #{Configs.output}"
+end

data/lib/code_object/base.rb

@@ -0,0 +1,48 @@
+# ../data.img#1787927:1
+require_relative '../token/container'
+require_relative '../dom/dom'
+require_relative '../parser/meta_container'
+
+#
+# ![Code Object Overview](../uml/CodeObject.svg)
+#
+#
+module CodeObject
+
+  class Base
+
+    include Token::Container
+    include Dom::Node
+    include Parser::MetaContainer
+      
+    attr_reader :docs, :name, :path
+    
+    # The name instance variable is required by Dom::Node
+    def initialize(path = "NO_PATH_SPECIFIED")      
+      path = path.to_s.split(/\s/).first # remove trailing spaces    
+      @path, @name = path, extract_name_from(path)
+      super()
+    end    
+    
+    def to_s
+      token_names = @tokens.keys if @tokens
+      "#<#{self.class}:#{self.name} @parent=#{parent.name if parent} @children=#{@children.keys} @tokens=#{token_names}>"
+    end    
+    
+    # Automatically converts markdown-documentation to html
+    def docs=(docstring)
+      @docs = docstring.strip
+    end
+    
+    protected
+    
+    # This is a Helpermethod, which can be used in subclasses like CodeObject::Function
+    def self.token_reader(name, token = name)
+      define_method name do
+        self.token(token)
+      end
+    end   
+  
+  end
+ 
+end