solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/aggregator.rb

@@ -0,0 +1,200 @@
+require 'jsduck/logger'
+
+module JsDuck
+
+  # Groups parsed documentation data from source files into classes.
+  #
+  # Produces Hash of classes as result.  When a member is found that
+  # doesn't belong to any class, it's placed into special "global"
+  # class.
+  class Aggregator
+    def initialize
+      @classes = {}
+      @alt_names = {}
+      @orphans = []
+      @current_class = nil
+    end
+
+    # Combines chunk of parsed JavaScript together with previously
+    # added chunks.  The resulting documentation is accumulated inside
+    # this class and can be later accessed through #result method.
+    #
+    # - file  SoureFile class instance
+    #
+    def aggregate(file)
+      @current_class = nil
+      file.each {|doc| register(doc) }
+    end
+
+    # Returns the final result which is a Hash of all classes indexed
+    # by name.  It's a hash because some processors applied to this
+    # returned classes list need a random-access look up classes by
+    # name.
+    def result
+      classify_orphans
+      create_global_class
+      @classes
+    end
+
+    private
+
+    # Registers documentation node either as class or as member of
+    # some class.
+    def register(node)
+      if node[:tagname] == :class
+        add_class(node)
+      else
+        add_member(node)
+      end
+    end
+
+    # When class exists, merge it with class node.
+    # Otherwise add as new class.
+    def add_class(cls)
+      old_cls = @classes[cls[:name]]
+      if !old_cls && @alt_names[cls[:name]]
+        old_cls = @alt_names[cls[:name]]
+        warn_alt_name(cls)
+      end
+
+      if old_cls
+        merge_classes(old_cls, cls)
+        @current_class = old_cls
+      else
+        @current_class = cls
+        @classes[cls[:name]] = cls
+
+        # Register all alternate names of class for lookup too
+        cls[:alternateClassNames].each do |altname|
+          if cls[:name] == altname
+            # A buggy documentation, warn.
+            warn_alt_name(cls)
+          else
+            @alt_names[altname] = cls
+            # When an alternate name has been used as a class name before,
+            # then this is one crappy documentation, but attempt to handle
+            # it by merging the class with alt-name into this class.
+            if @classes[altname]
+              merge_classes(cls, @classes[altname])
+              @classes.delete(altname)
+              warn_alt_name(cls)
+            end
+          end
+        end
+
+        insert_orphans(cls)
+      end
+    end
+
+    def warn_alt_name(cls)
+      Logger.warn(:alt_name, "Name #{cls[:name]} used as both classname and alternate classname", cls[:files][0])
+    end
+
+    # Merges new class-doc into old one.
+    def merge_classes(old, new)
+      # Merge booleans
+      [:extends, :singleton, :private].each do |tag|
+        old[tag] = old[tag] || new[tag]
+      end
+      # Merge arrays
+      [:mixins, :alternateClassNames, :requires, :uses, :files].each do |tag|
+        old[tag] = (old[tag] || []) + (new[tag] || [])
+      end
+      # Merge hashes of arrays
+      [:aliases].each do |tag|
+        new[tag].each_pair do |key, contents|
+          old[tag][key] = (old[tag][key] || []) + contents
+        end
+      end
+      old[:doc] = old[:doc].length > 0 ? old[:doc] : new[:doc]
+      # Additionally the doc-comment can contain configs and constructor
+      old[:members] += new[:members]
+    end
+
+    # Tries to place members into classes where they belong.
+    #
+    # @member explicitly defines the containing class, but we can meet
+    # item with @member=Foo before we actually meet class Foo - in
+    # that case we register them as orphans.  (Later when we finally
+    # meet class Foo, orphans are inserted into it.)
+    #
+    # Items without @member belong by default to the preceding class.
+    # When no class precedes them - they too are orphaned.
+    def add_member(node)
+      # Completely ignore member if @ignore used
+      return if node[:ignore]
+
+      if node[:owner]
+        if @classes[node[:owner]]
+          add_to_class(@classes[node[:owner]], node)
+        else
+          add_orphan(node)
+        end
+      elsif @current_class
+        node[:owner] = @current_class[:name]
+        add_to_class(@current_class, node)
+      else
+        add_orphan(node)
+      end
+    end
+
+    def add_to_class(cls, member)
+      cls[:members] << member
+    end
+
+    def add_orphan(node)
+      @orphans << node
+    end
+
+    # Inserts available orphans to class
+    def insert_orphans(cls)
+      members = @orphans.find_all {|node| node[:owner] == cls[:name] }
+      members.each do |node|
+        add_to_class(cls, node)
+        @orphans.delete(node)
+      end
+    end
+
+    # Creates classes for orphans that have :owner property defined,
+    # and then inserts orphans to these classes.
+    def classify_orphans
+      # Clone the orphans array first to avoid problems with
+      # #inster_orphan method deleting items from @orphans array.
+      @orphans.clone.each do |orph|
+        if orph[:owner]
+          class_name = orph[:owner]
+          if !@classes[class_name]
+            # this will add the class and add all orphans to it
+            add_empty_class(class_name)
+          end
+        end
+      end
+    end
+
+    # Creates class with name "global" and inserts all the remaining
+    # orphans into it (but only if there are any orphans).
+    def create_global_class
+      return if @orphans.length == 0
+
+      add_empty_class("global", "Global variables and functions.")
+      @orphans.each do |orph|
+        orph[:owner] = "global"
+        add_member(orph)
+      end
+      @orphans = []
+    end
+
+    def add_empty_class(name, doc = "")
+      add_class({
+        :tagname => :class,
+        :name => name,
+        :doc => doc,
+        :alternateClassNames => [],
+        :members => [],
+        :aliases => {},
+        :files => [{:filename => "", :linenr => 0, :href => ""}],
+      })
+    end
+  end
+
+end

data/lib/jsduck/app.rb

@@ -0,0 +1,63 @@
+require 'jsduck/batch_parser'
+require 'jsduck/batch_processor'
+require 'jsduck/assets'
+require 'jsduck/tag_registry'
+require 'jsduck/export_writer'
+require 'jsduck/web/writer'
+require 'jsduck/logger'
+
+module JsDuck
+
+  # The main application logic of jsduck
+  class App
+    # Initializes app with JsDuck::OptionsRecord object
+    def initialize(opts)
+      @opts = opts
+    end
+
+    # Main App logic.
+    # Returns application exit code.
+    def run
+      parse
+
+      init_assets
+
+      if @opts.export
+        generate_export
+      else
+        generate_web_page
+      end
+
+      if @opts.warnings_exit_nonzero && Logger.warnings_logged?
+        return 2
+      else
+        return 0
+      end
+    end
+
+    private
+
+    def parse
+      @parsed_files = BatchParser.parse(@opts)
+      @relations = BatchProcessor.process(@parsed_files, @opts)
+    end
+
+    def init_assets
+      # Initialize guides, videos, examples, ...
+      @assets = Assets.new(@relations, @opts)
+
+      # HACK: Give access to assets from @aside tag
+      TagRegistry.get_by_name(:aside).assets = @assets
+    end
+
+    def generate_export
+      ExportWriter.new(@relations, @assets, @opts).write
+    end
+
+    def generate_web_page
+      Web::Writer.new(@relations, @assets, @parsed_files, @opts).write
+    end
+
+  end
+
+end

data/lib/jsduck/assets.rb

@@ -0,0 +1,54 @@
+require 'jsduck/img/dir_set'
+require 'jsduck/img/writer'
+require 'jsduck/welcome'
+require 'jsduck/guides'
+require 'jsduck/videos'
+require 'jsduck/examples'
+require 'jsduck/categories/factory'
+require 'jsduck/format/doc'
+require 'jsduck/news'
+
+module JsDuck
+
+  # Binds together: Welcome page, Categories, Images, Guides, Videos,
+  # Examples.
+  #
+  # Often we need to pass guides/videos/examples/... to several
+  # classes. Having all these assets together in here, means we just
+  # need to pass one value instead of 3 or more.
+  class Assets
+    attr_reader :images
+    attr_reader :welcome
+    attr_reader :guides
+    attr_reader :videos
+    attr_reader :examples
+    attr_reader :categories
+    attr_reader :news
+
+    def initialize(relations, opts)
+      @relations = relations
+      @opts = opts
+
+      doc_formatter = Format::Doc.new(@relations, @opts)
+
+      @images = Img::DirSet.new(@opts.images, "images")
+      @welcome = Welcome.create(@opts.welcome, doc_formatter)
+      @guides = Guides.create(@opts.guides, doc_formatter, @opts)
+      @videos = Videos.create(@opts.videos)
+      @examples = Examples.create(@opts.examples, @opts)
+      @categories = Categories::Factory.create(@opts.categories, doc_formatter, @relations)
+      @news = News.create(@relations, doc_formatter, @opts)
+    end
+
+    # Writes out the assets that can be written out separately:
+    # guides, images.
+    #
+    # Welcome page and categories are written in JsDuck::IndexHtml
+    def write
+      @guides.write(@opts.output+"/guides")
+      Img::Writer.copy(@images.all_used, @opts.output+"/images")
+    end
+
+  end
+
+end

data/lib/jsduck/base_type.rb

@@ -0,0 +1,53 @@
+require 'jsduck/member_registry'
+
+module JsDuck
+
+  # Detects the type of documentation object: class, method, cfg, etc
+  class BaseType
+    # Given parsed documentation and code, returns the tagname for
+    # documentation item.
+    #
+    # @param doc_map Result from DocParser turned into hash of tags.
+    # @param code Result from Ast#detect or CssParser#parse
+    # @returns :class or any of the member type symbols (:method, :event, ...).
+    #
+    def self.detect(doc_map, code)
+      if doc_map[:class] || doc_map[:override]
+        :class
+      elsif type = detect_member(doc_map)
+        type
+      elsif doc_map[:type]
+        # @type also results in property
+        :property
+      elsif code[:tagname] == :class
+        :class
+      elsif code[:tagname] == :css_mixin
+        :css_mixin
+      elsif doc_map[:cfg]
+        :cfg
+      elsif doc_map[:constructor]
+        :method
+      elsif doc_map[:params] || doc_map[:return]
+        :method
+      else
+        code[:tagname]
+      end
+    end
+
+    # Detects any of the members defined using a Tag class.
+    # Returns the detected member type on success.
+    # Otherwise nil.
+    def self.detect_member(doc_map)
+      type = MemberRegistry.names.find {|type| doc_map[type] }
+
+      if type == :cfg
+        # Only detect a single @cfg as a :cfg.
+        # Multiple ones can be part of a class.
+        return (doc_map[:cfg].length == 1) ? :cfg : nil
+      else
+        type
+      end
+    end
+  end
+
+end

data/lib/jsduck/batch_parser.rb

@@ -0,0 +1,46 @@
+require 'jsduck/util/parallel'
+require 'jsduck/util/io'
+require 'jsduck/parser'
+require 'jsduck/source/file'
+require 'jsduck/logger'
+require 'jsduck/cache'
+
+module JsDuck
+
+  # Parses of all input files.  Input files are read from options
+  # object (originating from command line).
+  class BatchParser
+
+    def self.parse(opts)
+      cache = Cache.create(opts)
+
+      results = Util::Parallel.map(opts.input_files) do |fname|
+        Logger.log("Parsing", fname)
+
+        begin
+          source = Util::IO.read(fname)
+          docs = nil
+
+          unless docs = cache.read(fname, source)
+            docs = Parser.new.parse(source, fname, opts)
+            cache.write(fname, source, docs)
+          end
+
+          {
+            :file => Source::File.new(source, docs, fname),
+            :cache => cache.previous_entry,
+          }
+        rescue
+          Logger.fatal_backtrace("Error while parsing #{fname}", $!)
+          exit(1)
+        end
+      end
+
+      cache.cleanup( results.map {|r| r[:cache] }.compact )
+
+      return results.map {|r| r[:file] }
+    end
+
+  end
+
+end

data/lib/jsduck/batch_processor.rb

@@ -0,0 +1,83 @@
+require 'jsduck/aggregator'
+require 'jsduck/class'
+require 'jsduck/relations'
+require 'jsduck/logger'
+require 'jsduck/util/singleton'
+require 'jsduck/process/ignored_classes'
+require 'jsduck/process/global_members'
+require 'jsduck/process/enums'
+require 'jsduck/process/accessors'
+require 'jsduck/process/ext4_events'
+require 'jsduck/process/overrides'
+require 'jsduck/process/inherit_doc'
+require 'jsduck/process/versions'
+require 'jsduck/process/return_values'
+require 'jsduck/process/fires'
+require 'jsduck/process/components'
+require 'jsduck/process/lint'
+require 'jsduck/process/no_doc'
+require 'jsduck/process/circular_deps'
+
+module JsDuck
+
+  # Processes the parsing results into Relations object.
+  class BatchProcessor
+    include Util::Singleton
+
+    # Processes array of Source::File objects from BatchParser and
+    # returns instance of Relations class.
+    def process(parsed_files, opts)
+      r = aggregate(parsed_files)
+      r = pre_process(r, opts)
+      r = to_class_objects(r, opts)
+      return post_process(r, opts)
+    end
+
+    private
+
+    # Aggregates parsing results sequencially
+    def aggregate(parsed_files)
+      agr = Aggregator.new
+      parsed_files.each do |file|
+        Logger.log("Aggregating", file.filename)
+        agr.aggregate(file)
+      end
+      agr.result
+    end
+
+    # Do all kinds of processing on the classes hash before turning it
+    # into Relations object.
+    def pre_process(classes_hash, opts)
+      Process::IgnoredClasses.new(classes_hash).process_all!
+      Process::GlobalMembers.new(classes_hash, opts).process_all!
+      Process::Accessors.new(classes_hash).process_all!
+      Process::Ext4Events.new(classes_hash, opts).process_all!
+      Process::Enums.new(classes_hash).process_all!
+      Process::Overrides.new(classes_hash, opts).process_all!
+
+      classes_hash.values
+    end
+
+    # Turns all aggregated data into Class objects and places the
+    # classes inside Relations container.
+    def to_class_objects(docs, opts)
+      classes = docs.map {|d| Class.new(d) }
+      Relations.new(classes, opts.external)
+    end
+
+    # Do all kinds of post-processing on Relations object.
+    def post_process(relations, opts)
+      Process::CircularDeps.new(relations).process_all!
+      Process::InheritDoc.new(relations).process_all!
+      Process::Versions.new(relations, opts).process_all!
+      Process::ReturnValues.new(relations).process_all!
+      Process::Fires.new(relations).process_all!
+      Process::Components.new(relations).process_all!
+      Process::Lint.new(relations).process_all!
+      Process::NoDoc.new(relations).process_all!
+      relations
+    end
+
+  end
+
+end