RubyGems - jsduck - Versions diffs - 4.0.1 → 4.1.1 - Mend

jsduck 4.0.1 → 4.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (91) hide show

data/Rakefile +14 -0
data/esprima/esprima.js +210 -85
data/jsduck.gemspec +3 -3
data/lib/jsduck/accessors.rb +10 -8
data/lib/jsduck/aggregator.rb +7 -7
data/lib/jsduck/app.rb +24 -164
data/lib/jsduck/app_data.rb +2 -4
data/lib/jsduck/assets.rb +5 -2
data/lib/jsduck/ast.rb +9 -4
data/lib/jsduck/batch_formatter.rb +54 -0
data/lib/jsduck/batch_parser.rb +106 -0
data/lib/jsduck/categories.rb +5 -6
data/lib/jsduck/class.rb +77 -239
data/lib/jsduck/class_doc_expander.rb +0 -5
data/lib/jsduck/class_formatter.rb +14 -10
data/lib/jsduck/class_name.rb +23 -0
data/lib/jsduck/class_writer.rb +9 -8
data/lib/jsduck/doc_ast.rb +5 -6
data/lib/jsduck/doc_formatter.rb +61 -272
data/lib/jsduck/enum.rb +4 -4
data/lib/jsduck/esprima.rb +10 -4
data/lib/jsduck/examples.rb +5 -5
data/lib/jsduck/export_writer.rb +62 -0
data/lib/jsduck/exporter/app.rb +62 -0
data/lib/jsduck/exporter/examples.rb +58 -0
data/lib/jsduck/exporter/full.rb +60 -0
data/lib/jsduck/file_categories.rb +7 -4
data/lib/jsduck/function_ast.rb +99 -0
data/lib/jsduck/grouped_asset.rb +27 -16
data/lib/jsduck/guide_writer.rb +8 -7
data/lib/jsduck/guides.rb +31 -29
data/lib/jsduck/icons.rb +12 -1
data/lib/jsduck/images.rb +3 -3
data/lib/jsduck/importer.rb +7 -7
data/lib/jsduck/index_html.rb +20 -6
data/lib/jsduck/inherit_doc.rb +9 -12
data/lib/jsduck/inline/example.rb +42 -0
data/lib/jsduck/inline/img.rb +55 -0
data/lib/jsduck/inline/link.rb +227 -0
data/lib/jsduck/inline/video.rb +67 -0
data/lib/jsduck/inline_examples.rb +7 -7
data/lib/jsduck/js_parser.rb +5 -4
data/lib/jsduck/lint.rb +14 -2
data/lib/jsduck/logger.rb +5 -6
data/lib/jsduck/members_index.rb +132 -0
data/lib/jsduck/merger.rb +3 -9
data/lib/jsduck/options.rb +39 -41
data/lib/jsduck/override.rb +3 -7
data/lib/jsduck/relations.rb +9 -9
data/lib/jsduck/renderer.rb +3 -3
data/lib/jsduck/return_values.rb +72 -0
data/lib/jsduck/search_data.rb +16 -20
data/lib/jsduck/shortener.rb +58 -0
data/lib/jsduck/signature_renderer.rb +1 -2
data/lib/jsduck/source/file.rb +98 -0
data/lib/jsduck/source/file_parser.rb +72 -0
data/lib/jsduck/source/writer.rb +89 -0
data/lib/jsduck/tag/aside.rb +1 -1
data/lib/jsduck/tag/since.rb +1 -1
data/lib/jsduck/template_dir.rb +2 -2
data/lib/jsduck/util/html.rb +27 -0
data/lib/jsduck/util/io.rb +32 -0
data/lib/jsduck/util/json.rb +60 -0
data/lib/jsduck/util/null_object.rb +23 -0
data/lib/jsduck/util/os.rb +14 -0
data/lib/jsduck/util/parallel.rb +34 -0
data/lib/jsduck/util/singleton.rb +35 -0
data/lib/jsduck/util/stdout.rb +33 -0
data/lib/jsduck/videos.rb +5 -5
data/lib/jsduck/web_writer.rb +79 -0
data/lib/jsduck/welcome.rb +6 -6
data/spec/class_factory.rb +20 -0
metadata +32 -20
data/lib/jsduck/api_exporter.rb +0 -48
data/lib/jsduck/app_exporter.rb +0 -60
data/lib/jsduck/examples_exporter.rb +0 -56
data/lib/jsduck/full_exporter.rb +0 -35
data/lib/jsduck/html.rb +0 -25
data/lib/jsduck/inline_img.rb +0 -53
data/lib/jsduck/inline_video.rb +0 -58
data/lib/jsduck/io.rb +0 -30
data/lib/jsduck/json_duck.rb +0 -52
data/lib/jsduck/lexer.rb +0 -251
data/lib/jsduck/null_object.rb +0 -19
data/lib/jsduck/os.rb +0 -11
data/lib/jsduck/parallel_wrap.rb +0 -32
data/lib/jsduck/source_file.rb +0 -97
data/lib/jsduck/source_file_parser.rb +0 -70
data/lib/jsduck/source_writer.rb +0 -87
data/lib/jsduck/stats.rb +0 -103
data/lib/jsduck/stdout.rb +0 -31

data/lib/jsduck/source/writer.rb ADDED

@@ -0,0 +1,89 @@
+require 'jsduck/logger'
+require 'jsduck/util/parallel'
+require 'fileutils'
+module JsDuck
+  module Source
+    # Writes HTML JavaScript/CSS source into HTML files.
+    class Writer
+      def initialize(source_files)
+        @source_files = source_files
+      end
+      # Writes all source files as HTML files into destination dir.
+      def write(destination)
+        generate_html_filenames
+        FileUtils.mkdir(destination)
+        Util::Parallel.each(@source_files) do |file|
+          Logger.log("Writing source", file.html_filename)
+          write_single(destination + "/" + file.html_filename, file.to_html)
+        end
+      end
+      private
+      # Generates unique HTML filenames for each file.
+      #
+      # Can't be done in parallel for obvious reasons, but also
+      # because file.html_filename= method updates all the doc-objects
+      # related to the file.
+      def generate_html_filenames
+        filenames = {}
+        @source_files.each do |file|
+          i = 0
+          begin
+            name = html_filename(file.filename, i)
+            ci_name = name.downcase # case insensitive name
+            i += 1
+          end while filenames.has_key?(ci_name)
+          filenames[ci_name] = true
+          file.html_filename = name
+        end
+      end
+      # Returns HTML filename for n'th file with given name.
+      #
+      # html_filename("Foo.js", 0) => "Foo.html"
+      # html_filename("Foo.js", 1) => "Foo2.html"
+      # html_filename("Foo.js", 2) => "Foo3.html"
+      #
+      def html_filename(filename, nr=0)
+        ::File.basename(filename, ".js") + (nr > 0 ? (nr+1).to_s : "") + ".html"
+      end
+      def write_single(filename, source)
+        ::File.open(filename, 'w') {|f| f.write(wrap_page(source)) }
+      end
+      # Returns source wrapped inside HTML page
+      def wrap_page(source)
+        return <<-EOHTML
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>The source code</title>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
+</head>
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js">#{source}</pre>
+</body>
+</html>
+      EOHTML
+      end
+    end
+  end
+end

data/lib/jsduck/tag/aside.rb CHANGED

@@ -65,7 +65,7 @@ module JsDuck::Tag
     def warn(msg)
       ctx = @context ? @context[:files][0] : {}
-      JsDuck::Logger.instance.warn(:aside, msg, ctx[:filename], ctx[:linenr])
+      JsDuck::Logger.warn(:aside, msg, ctx[:filename], ctx[:linenr])
       nil
     end

data/lib/jsduck/tag/since.rb CHANGED

@@ -11,7 +11,7 @@ module JsDuck::Tag
     def to_value(contents)
       if contents.length > 1
-        JsDuck::Logger.instance.warn(nil, "Only one @since tag allowed per class/member.")
+        JsDuck::Logger.warn(nil, "Only one @since tag allowed per class/member.")
       end
       contents[0]
     end

data/lib/jsduck/template_dir.rb CHANGED

@@ -21,10 +21,10 @@ module JsDuck
     def write
       FileUtils.mkdir(@opts.output_dir)
       if @opts.template_links
-        Logger.instance.log("Linking template files to", @opts.output_dir)
+        Logger.log("Linking template files to", @opts.output_dir)
         move_files(:symlink)
       else
-        Logger.instance.log("Copying template files to", @opts.output_dir)
+        Logger.log("Copying template files to", @opts.output_dir)
         move_files(:cp_r)
       end

data/lib/jsduck/util/html.rb ADDED

@@ -0,0 +1,27 @@
+require 'cgi'
+module JsDuck
+  module Util
+    # Helpers for dealing with HTML
+    class HTML
+      # Strips tags from HTML text
+      def self.strip_tags(html)
+        html.gsub(/<.*?>/, "")
+      end
+      # Escapes HTML, replacing < with &lt; ...
+      def self.escape(html)
+        CGI.escapeHTML(html)
+      end
+      # Unescapes HTML, replacing &lt; with < ...
+      def self.unescape(html)
+        CGI.unescapeHTML(html)
+      end
+    end
+  end
+end

data/lib/jsduck/util/io.rb ADDED

@@ -0,0 +1,32 @@
+module JsDuck
+  module Util
+    # A helper to use instead the builtin IO class to read files in
+    # correct encoding.
+    #
+    # By default in Ruby 1.9 the encoding is auto-detected, which can
+    # have surprising results.  So in here we read in all files in UTF-8
+    # (the default) or in some other encoding specified through --encoding
+    # option and convert it to UTF-8 internally.
+    class IO
+      @@encoding = "UTF-8"
+      # Sets the external encoding to be used for reading files.
+      # When it's different from UTF-8, the input will be converted to UTF-8.
+      def self.encoding=(e)
+        if e =~ /^UTF-8$/i
+          @@encoding = e
+        else
+          @@encoding = e+":UTF-8"
+        end
+      end
+      # Reads given filename into string
+      def self.read(filename)
+        File.open(filename, "r:"+@@encoding) {|f| f.read }
+      end
+    end
+  end
+end

data/lib/jsduck/util/json.rb ADDED

@@ -0,0 +1,60 @@
+require 'jsduck/util/singleton'
+require 'jsduck/util/io'
+require 'jsduck/logger'
+require 'json'
+module JsDuck
+  module Util
+    # Wrapper around the json gem for use in JsDuck.
+    #
+    # The main benefit of it is that we have a central place for
+    # controlling how the JSON is created (pretty-formatted or not).
+    class Json
+      include Util::Singleton
+      def initialize
+        @pretty = false
+      end
+      # Set to true to turn on pretty-formatting of JSON
+      def pretty=(pretty)
+        @pretty = pretty
+      end
+      # Turns object into JSON, places it inside JavaScript that calls the
+      # given callback name, and writes the result to file.
+      def write_jsonp(filename, callback_name, data)
+        jsonp = "Ext.data.JsonP." + callback_name + "(" + generate(data) + ");"
+        File.open(filename, 'w') {|f| f.write(jsonp) }
+      end
+      # Turns object into JSON and writes inside a file
+      def write_json(filename, data)
+        File.open(filename, 'w') {|f| f.write(generate(data)) }
+      end
+      # Generates JSON from object
+      def generate(data)
+        @pretty ? JSON.pretty_generate(data) : JSON.generate(data)
+      end
+      # Reads and parses JSON from file
+      def read(filename)
+        begin
+          parse(Util::IO.read(filename))
+        rescue
+          Logger.fatal("#{filename} is not a valid JSON file")
+          exit(1)
+        end
+      end
+      # Parses JSON string
+      def parse(string, opts = {})
+        JSON.parse(string, opts)
+      end
+    end
+  end
+end

data/lib/jsduck/util/null_object.rb ADDED

@@ -0,0 +1,23 @@
+module JsDuck
+  module Util
+    # A class that does nothing.
+    # Responds to all methods by returning self, unless a hash passed to
+    # constructor.
+    # See: http://en.wikipedia.org/wiki/Null_Object_pattern
+    class NullObject
+      # Optionally takes a hash of method_name => return_value pairs,
+      # making it return those values for those methods, sort of like
+      # OpenStruct, but for all other methods self is still returned and
+      # any number of arguments is accepted.
+      def initialize(methods={})
+        @methods = methods
+      end
+      def method_missing(meth, *args, &block)
+        @methods.has_key?(meth) ? @methods[meth] : self
+      end
+    end
+  end
+end

data/lib/jsduck/util/os.rb ADDED

@@ -0,0 +1,14 @@
+require 'rbconfig'
+module JsDuck
+  module Util
+    # Simple helper class to detect operating system
+    class OS
+      def self.windows?
+        RbConfig::CONFIG['host_os'] =~ /mswin|mingw|cygwin/
+      end
+    end
+  end
+end

data/lib/jsduck/util/parallel.rb ADDED

@@ -0,0 +1,34 @@
+require 'parallel'
+module JsDuck
+  module Util
+    # Wrapper around the parallel gem that falls back to simple
+    # Array#map and Array#each when :in_processes => 0 specified.
+    class Parallel
+      @@in_processes = nil
+      # Sets globally the nr of processes to use.
+      def self.in_processes=(n)
+        @@in_processes = n
+      end
+      def self.each(arr, &block)
+        if @@in_processes == 0
+          arr.each &block
+        else
+          ::Parallel.each(arr, {:in_processes => @@in_processes}, &block)
+        end
+      end
+      def self.map(arr, &block)
+        if @@in_processes == 0
+          arr.map &block
+        else
+          ::Parallel.map(arr, {:in_processes => @@in_processes}, &block)
+        end
+      end
+    end
+  end
+end

data/lib/jsduck/util/singleton.rb ADDED

@@ -0,0 +1,35 @@
+require 'singleton'
+module JsDuck
+  module Util
+    # A more convenient Singleton implementation.
+    #
+    # With the standard ruby Singleton you need to call the methods of
+    # your singleton instance as follows:
+    #
+    #     MyClass.instance.my_method()
+    #
+    # But with JsDuck::Util::Singleton you can skip the .instance. part:
+    #
+    #     MyClass.my_method()
+    #
+    # This also conveniently hides from the calling code the fact that
+    # a class is implemented as Singleton - it could just as well only
+    # have static methods.
+    #
+    module Singleton
+      def self.included(base)
+        base.class_eval do
+          include ::Singleton
+          # Redirect calls from MyClass.method to MyClass.instance.method
+          def self.method_missing(meth, *args, &block)
+            self.instance.send(meth, *args, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsduck/util/stdout.rb ADDED

@@ -0,0 +1,33 @@
+require 'jsduck/util/json'
+require 'jsduck/util/singleton'
+module JsDuck
+  module Util
+    # Central place for buffering JSON data that's meant to be written to STDOUT
+    class Stdout
+      include Util::Singleton
+      def initialize
+        @data = nil
+      end
+      # Adds array of new data
+      def add(data)
+        if @data
+          @data += data
+        else
+          @data = data
+        end
+      end
+      # Writes data to STDOUT in JSON format,
+      # but only if some data was added.
+      def flush
+        puts Util::Json.generate(@data) if @data
+      end
+    end
+  end
+end

data/lib/jsduck/videos.rb CHANGED

@@ -1,5 +1,5 @@
-require 'jsduck/json_duck'
-require 'jsduck/null_object'
+require 'jsduck/util/json'
+require 'jsduck/util/null_object'
 require 'jsduck/grouped_asset'
 module JsDuck
@@ -11,14 +11,14 @@ module JsDuck
       if filename
         Videos.new(filename)
       else
-        NullObject.new(:to_array => [], :[] => nil)
+        Util::NullObject.new(:to_array => [], :[] => nil)
       end
     end
     def initialize(filename)
-      @groups = JsonDuck.read(filename)
+      @groups = Util::Json.read(filename)
       add_names_if_missing
-      build_map_by_name("Two videos have the same name", filename)
+      build_map_by_name
     end
     # Each video should have a name, which is used in URL to reference the video.

data/lib/jsduck/web_writer.rb ADDED

@@ -0,0 +1,79 @@
+require 'jsduck/exporter/app'
+require 'jsduck/batch_formatter'
+require 'jsduck/template_dir'
+require 'jsduck/index_html'
+require 'jsduck/app_data'
+require 'jsduck/class_writer'
+require 'jsduck/source/writer'
+require 'jsduck/inline_examples'
+require 'fileutils'
+module JsDuck
+  # Performs the generation of docs web app.
+  class WebWriter
+    def initialize(relations, assets, parsed_files, opts)
+      @relations = relations
+      @assets = assets
+      @parsed_files = parsed_files
+      @opts = opts
+    end
+    def write
+      clean_output_dir
+      write_template_files
+      write_app_data
+      # class-formatting is done in parallel which breaks the links
+      # between source files and classes. Therefore it MUST to be done
+      # after writing sources which needs the links to work.
+      write_source if @opts.source
+      format_classes
+      write_inline_examples if @opts.tests
+      write_classes
+      @assets.write
+    end
+    def write_template_files
+      TemplateDir.new(@opts).write
+      IndexHtml.new(@assets, @opts).write
+    end
+    def write_app_data
+      AppData.new(@relations, @assets, @opts).write(@opts.output_dir+"/data.js")
+    end
+    def write_source
+      source_writer = Source::Writer.new(@parsed_files)
+      source_writer.write(@opts.output_dir + "/source")
+    end
+    def write_inline_examples
+      examples = InlineExamples.new
+      examples.add_classes(@relations)
+      examples.add_guides(@assets.guides)
+      examples.write(@opts.output_dir+"/inline-examples.js")
+    end
+    def write_classes
+      class_writer = ClassWriter.new(Exporter::App, @relations, @opts)
+      class_writer.write(@opts.output_dir+"/output", ".js")
+    end
+    # -- util routines --
+    def clean_output_dir
+      FileUtils.rm_rf(@opts.output_dir)
+    end
+    def format_classes
+      BatchFormatter.format_all!(@relations, @assets, @opts)
+    end
+  end
+end