ragaskar-jsdoc_helper 0.0.2.1

data/lib/jsdoc_helper/rake/task.rb

@@ -0,0 +1,43 @@
+require 'forwardable'
+module JsdocHelper
+  module Rake
+    # Encapsulates rake tasks for generating jsdoc documentation
+    # 
+    # example:
+    #   JsdocHelper::Rake::Task.new do |t|
+    #     t[:toolkit] = '/usr/local/lib/jsdoc-toolkit'
+    #     t[:files] << 'ext'
+    #     t[:template] = 'templates/jsdoc_custom'
+    #     t[:out] = 'html'
+    #     t[:options] = '--private'
+    #   end
+    # 
+    class Task
+      
+      extend Forwardable
+      def_delegators :runner, :[]=
+      
+      DEFAULT_NAME = 'jsdoc'
+            
+      # Create a new jsdoc-toolkit task. If a block is passed, the task object will be passed as an argument to the block.
+      def initialize(task_name=DEFAULT_NAME)
+        yield self if block_given?
+        define_task(task_name)
+      end
+      
+      private
+      
+      def define_task(task_name)
+        desc "Generate jsdoc-toolkit documentation"
+        task task_name do
+          runner.run
+        end
+      end
+      
+      def runner
+        @runner ||= Runner.new
+      end
+      
+    end
+  end
+end

data/lib/jsdoc_helper/rake/task/runner.rb

@@ -0,0 +1,85 @@
+require 'forwardable'
+module JsdocHelper
+  module Rake
+    class Task
+      # Holds the arguments for, and runs, jsdoc-toolkit
+      class Runner
+        
+        extend Forwardable
+        def_delegator :@args, :[]=
+        
+        # The default jsdoc-toolkit to use
+        DEFAULT_TOOLKIT = JsdocHelper.path('ext', 'jsdoc-toolkit')
+        
+        # Default arguments
+        DEFAULT_ARGS = {
+          :toolkit => DEFAULT_TOOLKIT,
+          :files => FileList[File.join(%w(lib ** *.js))],
+          :template => "templates/jsdoc",
+          :out => FileList['doc'],
+          :options => ""
+        }
+        
+        # Create a new Runner, with arguments that will be merged with the defaults
+        def initialize(args={})
+          @args = default_args.merge(args)
+        end
+        
+        # Run jsdoc-toolkit. If <tt>:return_string => true</tt> is passed, the function will return any messages that it would have otherwise sent to stdout
+        def run(opts={})
+          msg = toolkit == DEFAULT_TOOLKIT ? '' : "using #{toolkit}"
+          
+          puts msg unless msg.empty?
+          system command
+          
+          msg.empty? || !opts[:return_string] ? true : msg
+        end
+        
+        # Return the command that the runner will run
+        def command
+          "#{jsrun} #{jsdoc} #{files} -t=#{template} -d=#{out} #{options}".strip
+        end
+        
+        private
+        
+        def default_args
+          @default_args ||= DEFAULT_ARGS
+        end
+        
+        def jsrun
+          "java -jar #{toolkit_path('jsrun.jar')}"
+        end
+        
+        def toolkit
+          File.expand_path(@args[:toolkit])
+        end
+        
+        def jsdoc
+          toolkit_path('app/run.js')
+        end
+        
+        def out
+          @args[:out].to_a.to_s
+        end
+        
+        def files
+          @args[:files].to_a.join(' ')
+        end
+        
+        def template
+          toolkit_path(@args[:template])
+        end
+        
+        def toolkit_path(relative_path)
+          File.join(toolkit, relative_path)
+        end
+        
+        def options
+          @args[:options].to_a.join(' ')
+        end
+        
+      end
+    end
+  end
+end
+

data/spec/jsdoc_helper/jsdoc_helper_spec.rb

@@ -0,0 +1,4 @@
+
+require File.expand_path(File.join(File.dirname(__FILE__), %w[.. spec_helper]))
+
+# EOF

data/spec/jsdoc_helper/rake/task/runner_spec.rb

@@ -0,0 +1,45 @@
+require File.expand_path(File.join(File.dirname(__FILE__), %w[.. .. .. spec_helper]))
+require JsdocHelper.path(%w(features support file_helper))
+
+module JsdocHelper
+  module Rake
+    class Task
+      
+      describe Runner do
+        
+        include FileHelper
+        
+        before do
+          @r = Runner.new
+          @approot = JsdocHelper.path
+          FileUtils.rm_rf working_dir
+          FileUtils.mkdir working_dir
+          create_dir('lib')
+          create_file('lib/test.js')
+        end
+        
+        it "should work with FileUtils and FileHelper the way I expect" do
+          in_working_dir do
+            `pwd`.should == "#{@approot}test/tmp\n"
+          end
+        end
+        
+        it "should have a useful default command with files" do
+          in_working_dir do
+            @r.command.should == "java -jar #{@approot}ext/jsdoc-toolkit/jsrun.jar #{@approot}ext/jsdoc-toolkit/app/run.js lib/test.js -t=#{@approot}ext/jsdoc-toolkit/templates/jsdoc -d=doc"
+          end
+        end
+        
+        it "should output a 'using' string when its using a different toolkit" do
+          @r[:toolkit] = '../ext/jsdoc-toolkit'
+          in_working_dir do
+            output = quietly { @r.run :return_string => true }
+            output.should =~ /using (.*)jsdoc-toolkit/
+          end
+        end
+                
+      end
+    
+    end
+  end
+end

data/spec/jsdoc_helper/support/file_helper_spec.rb

@@ -0,0 +1,93 @@
+require File.expand_path(File.join(File.dirname(__FILE__), %w[.. .. spec_helper]))
+require JsdocHelper.path(%w(features support file_helper))
+require 'fileutils'
+
+describe FileHelper do
+  
+  include FileHelper
+  
+  ::Spec::Matchers.define :exist_in do |fh|
+    match do |file_name|
+      fh.file_exist?(file_name)
+    end
+    failure_message_for_should do |file_name|
+      "'#{file_name}' does not exist in a file in '#{fh.working_dir}'"
+    end
+  end
+  
+  before do
+    FileUtils.rm_rf working_dir
+    FileUtils.mkdir working_dir
+  end
+  
+  it "should have a working directory" do
+    working_dir.should == JsdocHelper.path(%w(test tmp))
+  end
+  
+  it "should return a path to a file in the working directory" do
+    path('test').should == File.expand_path(JsdocHelper.path(%w(test tmp test)))
+  end
+  
+  it "should create a file" do
+    File.exist?(JsdocHelper.path(%w(test tmp test.file))).should be_false
+    create_file('test.file')
+    File.exist?(JsdocHelper.path(%w(test tmp test.file))).should be_true
+  end
+  
+  it "should create a directory" do
+    File.directory?(path('lib')).should be_false
+    create_dir('lib')
+    File.directory?(path('lib')).should be_true
+  end
+  
+  it "should create a file with content" do
+    create_file('test.txt', 'hi there this is content')
+    IO.read(path('test.txt')).should == "hi there this is content"
+  end
+  
+  it "should run a command and store the stdout, stderr, and last exit code" do
+    run('echo pandas')
+    last_stdout.should =~ /^pandas\n$/m
+    last_stderr.should be_empty
+    
+    run('echo panda error 1>&2')
+    last_stdout.should be_empty
+    last_stderr.should =~ /^panda error\n$/m
+    last_exit_status.should be(0)
+    
+    run('echo panda exits 1>&2; exit 1')
+    last_stdout.should be_empty
+    last_stderr.should =~ /^panda exits\n$/m
+    last_exit_status.should be(1)
+  end
+  
+  it "should detect if a file exists" do
+    'lib'.should_not exist_in(self)
+    'lib/test.file'.should_not exist_in(self)
+    'otherfile.txt'.should_not exist_in(self)
+    
+    create_dir('lib')
+    create_file('lib/test.file')
+    create_file('otherfile.txt')
+    
+    'lib'.should exist_in(self)
+    'lib/test.file'.should exist_in(self)
+    'otherfile.txt'.should exist_in(self)
+    'notafile.txt'.should_not exist_in(self)
+    'lib/stillnotafile.txt'.should_not exist_in(self)
+  end
+  
+  it "should produce a src prefix for documentation" do
+    doc_src_prefix.should =~ /^_Users_petegadomski_Developer_jsdoc_helper_test_tmp$/
+  end
+  
+  it "should return a nice file list" do
+    create_file('test1.js')
+    create_file('test2.js')
+    create_dir('lib')
+    create_file('lib/test3.js')
+    
+    file_list.join(' ').should == "lib lib/test3.js test1.js test2.js"
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,25 @@
+
+require File.expand_path(
+    File.join(File.dirname(__FILE__), %w[.. lib jsdoc_helper]))
+
+Spec::Runner.configure do |config|
+  # == Mock Framework
+  #
+  # RSpec uses it's own mocking framework by default. If you prefer to
+  # use mocha, flexmock or RR, uncomment the appropriate line:
+  #
+  # config.mock_with :mocha
+  # config.mock_with :flexmock
+  # config.mock_with :rr
+end
+
+def quietly
+  orig_stdout = $stdout
+  $stdout = File.open('/dev/null', 'w')
+  output = yield
+  $stdout.close
+  $stdout = orig_stdout
+  output
+end
+
+# EOF

metadata

@@ -0,0 +1,168 @@
+--- !ruby/object:Gem::Specification 
+name: ragaskar-jsdoc_helper
+version: !ruby/object:Gem::Version 
+  version: 0.0.2.1
+platform: ruby
+authors: 
+- Rajan Agaskar
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-23 00:00:00 -08:00
+default_executable: jsdoc_helper
+dependencies: []
+
+description: jsdoc_helper
+email: ragaskar@gmail.com
+executables: 
+- jsdoc_helper
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- bin/jsdoc_helper
+- ext/jsdoc-toolkit/README.txt
+- ext/jsdoc-toolkit/app/frame.js
+- ext/jsdoc-toolkit/app/frame/Chain.js
+- ext/jsdoc-toolkit/app/frame/Dumper.js
+- ext/jsdoc-toolkit/app/frame/Hash.js
+- ext/jsdoc-toolkit/app/frame/Link.js
+- ext/jsdoc-toolkit/app/frame/Namespace.js
+- ext/jsdoc-toolkit/app/frame/Opt.js
+- ext/jsdoc-toolkit/app/frame/Reflection.js
+- ext/jsdoc-toolkit/app/frame/String.js
+- ext/jsdoc-toolkit/app/frame/Testrun.js
+- ext/jsdoc-toolkit/app/handlers/FOODOC.js
+- ext/jsdoc-toolkit/app/handlers/XMLDOC.js
+- ext/jsdoc-toolkit/app/handlers/XMLDOC/DomReader.js
+- ext/jsdoc-toolkit/app/handlers/XMLDOC/XMLDoc.js
+- ext/jsdoc-toolkit/app/handlers/XMLDOC/XMLParse.js
+- ext/jsdoc-toolkit/app/lib/JSDOC.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/DocComment.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/DocTag.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/JsDoc.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/JsPlate.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/Lang.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/Parser.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/PluginManager.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/Symbol.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/SymbolSet.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/TextStream.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/Token.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/TokenReader.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/TokenStream.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/Util.js
+- ext/jsdoc-toolkit/app/lib/JSDOC/Walker.js
+- ext/jsdoc-toolkit/app/main.js
+- ext/jsdoc-toolkit/app/plugins/commentSrcJson.js
+- ext/jsdoc-toolkit/app/plugins/frameworkPrototype.js
+- ext/jsdoc-toolkit/app/plugins/functionCall.js
+- ext/jsdoc-toolkit/app/plugins/publishSrcHilite.js
+- ext/jsdoc-toolkit/app/plugins/symbolLink.js
+- ext/jsdoc-toolkit/app/plugins/tagParamConfig.js
+- ext/jsdoc-toolkit/app/plugins/tagSynonyms.js
+- ext/jsdoc-toolkit/app/run.js
+- ext/jsdoc-toolkit/app/t/TestDoc.js
+- ext/jsdoc-toolkit/app/t/runner.js
+- ext/jsdoc-toolkit/app/test.js
+- ext/jsdoc-toolkit/app/test/addon.js
+- ext/jsdoc-toolkit/app/test/anon_inner.js
+- ext/jsdoc-toolkit/app/test/augments.js
+- ext/jsdoc-toolkit/app/test/augments2.js
+- ext/jsdoc-toolkit/app/test/borrows.js
+- ext/jsdoc-toolkit/app/test/borrows2.js
+- ext/jsdoc-toolkit/app/test/config.js
+- ext/jsdoc-toolkit/app/test/constructs.js
+- ext/jsdoc-toolkit/app/test/encoding.js
+- ext/jsdoc-toolkit/app/test/encoding_other.js
+- ext/jsdoc-toolkit/app/test/event.js
+- ext/jsdoc-toolkit/app/test/functions_anon.js
+- ext/jsdoc-toolkit/app/test/functions_nested.js
+- ext/jsdoc-toolkit/app/test/global.js
+- ext/jsdoc-toolkit/app/test/globals.js
+- ext/jsdoc-toolkit/app/test/ignore.js
+- ext/jsdoc-toolkit/app/test/inner.js
+- ext/jsdoc-toolkit/app/test/jsdoc_test.js
+- ext/jsdoc-toolkit/app/test/lend.js
+- ext/jsdoc-toolkit/app/test/memberof.js
+- ext/jsdoc-toolkit/app/test/memberof_constructor.js
+- ext/jsdoc-toolkit/app/test/name.js
+- ext/jsdoc-toolkit/app/test/namespace_nested.js
+- ext/jsdoc-toolkit/app/test/nocode.js
+- ext/jsdoc-toolkit/app/test/oblit_anon.js
+- ext/jsdoc-toolkit/app/test/overview.js
+- ext/jsdoc-toolkit/app/test/param_inline.js
+- ext/jsdoc-toolkit/app/test/params_optional.js
+- ext/jsdoc-toolkit/app/test/prototype.js
+- ext/jsdoc-toolkit/app/test/prototype_nested.js
+- ext/jsdoc-toolkit/app/test/prototype_oblit.js
+- ext/jsdoc-toolkit/app/test/prototype_oblit_constructor.js
+- ext/jsdoc-toolkit/app/test/public.js
+- ext/jsdoc-toolkit/app/test/shared.js
+- ext/jsdoc-toolkit/app/test/shared2.js
+- ext/jsdoc-toolkit/app/test/shortcuts.js
+- ext/jsdoc-toolkit/app/test/static_this.js
+- ext/jsdoc-toolkit/app/test/synonyms.js
+- ext/jsdoc-toolkit/app/test/tosource.js
+- ext/jsdoc-toolkit/app/test/variable_redefine.js
+- ext/jsdoc-toolkit/changes.txt
+- ext/jsdoc-toolkit/conf/sample.conf
+- ext/jsdoc-toolkit/java/build.xml
+- ext/jsdoc-toolkit/java/build_1.4.xml
+- ext/jsdoc-toolkit/java/classes/js.jar
+- ext/jsdoc-toolkit/java/src/JsDebugRun.java
+- ext/jsdoc-toolkit/java/src/JsRun.java
+- ext/jsdoc-toolkit/jsdebug.jar
+- ext/jsdoc-toolkit/jsrun.jar
+- ext/jsdoc-toolkit/out/jsdoc/files.html
+- ext/jsdoc-toolkit/out/jsdoc/index.html
+- ext/jsdoc-toolkit/out/jsdoc/symbols/_global_.html
+- ext/jsdoc-toolkit/out/jsdoc/symbols/src/lib_test.js.html
+- ext/jsdoc-toolkit/templates/jsdoc/allclasses.tmpl
+- ext/jsdoc-toolkit/templates/jsdoc/allfiles.tmpl
+- ext/jsdoc-toolkit/templates/jsdoc/class.tmpl
+- ext/jsdoc-toolkit/templates/jsdoc/index.tmpl
+- ext/jsdoc-toolkit/templates/jsdoc/publish.js
+- ext/jsdoc-toolkit/templates/jsdoc/static/default.css
+- ext/jsdoc-toolkit/templates/jsdoc/static/header.html
+- ext/jsdoc-toolkit/templates/jsdoc/static/index.html
+- ext/jsdoc-toolkit/templates/jsdoc/symbol.tmpl
+- lib/jsdoc_helper.rb
+- lib/jsdoc_helper/rake/task.rb
+- lib/jsdoc_helper/rake/task/runner.rb
+- README.rdoc
+has_rdoc: true
+homepage: http://github.com/ragaskar/jsdoc_helper
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: jsdoc_helper
+test_files: 
+- spec/jsdoc_helper/jsdoc_helper_spec.rb
+- spec/jsdoc_helper/rake/task/runner_spec.rb
+- spec/jsdoc_helper/support/file_helper_spec.rb
+- spec/spec_helper.rb