jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/docs_code_comparer.rb

@@ -0,0 +1,31 @@
+require 'jsduck/util/singleton'
+
+module JsDuck
+
+  # Compares documentation and code hashes.
+  # Provides an utility method to help with merging.
+  class DocsCodeComparer
+    include Util::Singleton
+
+    # When docs has the key, returns value from there.
+    # When code has the key and matches with docs, gets value from there.
+    # Otherwise returns nil.
+    def merge_if_matches(key, docs, code)
+      if docs[key]
+        docs[key]
+      elsif code[key] && matches?(docs, code)
+        code[key]
+      else
+        nil
+      end
+    end
+
+    # True if the name detected from code matches with explicitly
+    # documented name.  Also true when no explicit name documented.
+    def matches?(docs, code)
+      return docs[:name] == nil || docs[:name] == code[:name]
+    end
+
+  end
+
+end

data/lib/jsduck/export_writer.rb

@@ -1,7 +1,7 @@
 require 'jsduck/util/stdout'
 require 'jsduck/exporter/full'
 require 'jsduck/exporter/examples'
-require 'jsduck/batch_formatter'
+require 'jsduck/format/batch'
 require 'jsduck/class_writer'
 require 'jsduck/guide_writer'
 require 'fileutils'
@@ -54,7 +54,7 @@ module JsDuck
     end
 
     def format_classes
-      BatchFormatter.format_all!(@relations, @assets, @opts)
+      Format::Batch.format_all!(@relations, @assets, @opts)
     end
 
   end

data/lib/jsduck/exporter/app.rb

@@ -1,6 +1,6 @@
-require 'jsduck/renderer'
-require 'jsduck/doc_formatter'
+require 'jsduck/render/class'
 require 'jsduck/exporter/full'
+require 'jsduck/tag_registry'
 
 module JsDuck
   module Exporter
@@ -9,7 +9,7 @@ module JsDuck
     class App < Full
       def initialize(relations, opts)
         super(relations, opts)
-        @renderer = Renderer.new(opts)
+        @renderer = Render::Class.new(opts)
       end
 
       # Returns compacted class data hash which contains an additional
@@ -28,6 +28,7 @@ module JsDuck
         cls[:members] = compact_members_group(cls[:members])
         cls[:statics] = compact_members_group(cls[:statics])
         cls[:files] = compact_files(cls[:files])
+        cls[:meta] = combine_meta(cls)
         cls
       end
 
@@ -41,12 +42,23 @@ module JsDuck
 
       def compact_member(m)
         m_copy = {}
-        [:name, :tagname, :owner, :meta, :id].each do |key|
+        [:name, :tagname, :owner, :id].each do |key|
           m_copy[key] = m[key]
         end
+        m_copy[:meta] = combine_meta(m)
         m_copy
       end
 
+      # Add data for builtin tags with signatures to :meta field.
+      def combine_meta(m)
+        meta = {}
+        TagRegistry.signatures.each do |s|
+          name = s[:tagname]
+          meta[name] = m[name] if m[name]
+        end
+        meta
+      end
+
       # Remove full path from filename for privacy considerations as the
       # path can reveal information about the system where JSDuck was
       # run.  The docs app doesn't need to have this information.

data/lib/jsduck/exporter/full.rb

@@ -1,4 +1,4 @@
-require 'jsduck/class'
+require 'jsduck/tag_registry'
 
 module JsDuck
   module Exporter
@@ -18,7 +18,7 @@ module JsDuck
 
         h[:members] = {}
         h[:statics] = {}
-        Class.each_member_type do |tagname|
+        TagRegistry.member_type_names.each do |tagname|
           h[:members][tagname] = export_members(cls, {:tagname => tagname, :static => false})
           h[:statics][tagname] = export_members(cls, {:tagname => tagname, :static => true})
         end

data/lib/jsduck/format/batch.rb

@@ -0,0 +1,58 @@
+require 'jsduck/util/parallel'
+require 'jsduck/format/class'
+require 'jsduck/format/doc'
+require 'jsduck/img/dir_set'
+require 'jsduck/logger'
+
+module JsDuck
+  module Format
+
+    # Performs the formatting of the doc-object of all classes.
+    class Batch
+
+      # Formats all classes.
+      # Also registers found images in assets.
+      def self.format_all!(relations, assets, opts)
+        # Format all doc-objects in parallel
+        formatted_classes = Util::Parallel.map(relations.classes) do |cls|
+
+          files = cls[:files].map {|f| f[:filename] }.join(" ")
+          Logger.log("Markdown formatting #{cls[:name]}", files)
+
+          formatter = create_class_formatter(relations, opts)
+          begin
+            {
+              :doc => formatter.format(cls.internal_doc),
+              :images => formatter.images.all_used
+            }
+          rescue
+            Logger.fatal_backtrace("Error while formatting #{cls[:name]} #{files}", $!)
+            exit(1)
+          end
+        end
+
+        # Then merge the data back to classes sequentially
+        formatted_classes.each do |cls|
+          relations[cls[:doc][:name]].internal_doc = cls[:doc]
+          # Perform lookup of all the images again.  We're really doing
+          # this work twice now, but as we usually don't have excessive
+          # amounts of images, the performance penalty should be minimal.
+          cls[:images].each {|img| assets.images.get(img[:filename]) }
+        end
+
+        # Print warnings for unused images
+        assets.images.report_unused
+      end
+
+      # Factory method to create new Format::Class instances.
+      def self.create_class_formatter(relations, opts)
+        doc_formatter = Format::Doc.new(relations, opts)
+        doc_formatter.images = Img::DirSet.new(opts.images, "images")
+
+        return Format::Class.new(doc_formatter)
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/format/class.rb

@@ -0,0 +1,62 @@
+require 'jsduck/tag_registry'
+
+module JsDuck
+  module Format
+
+    # Performs documentation formatting of a class and all of its
+    # members.
+    #
+    # The actual work is delegated to the #format methods of Tag
+    # classes, to which we pass the Format::Doc instance which they
+    # can use to perform the formatting.
+    #
+    # The formatting done by #format methods usually consists of
+    # turning :doc properties of class from markdown to HTML,
+    # resolving @links, and converting type definitions to HTML.
+    class Class
+      def initialize(formatter)
+        @formatter = formatter
+      end
+
+      # Runs the formatter on doc object of a class.
+      # Accessed using Class#internal_doc
+      def format(cls)
+        @formatter.class_context = cls[:name]
+        @formatter.doc_context = cls[:files][0]
+
+        format_tags(cls)
+
+        # format all members (except hidden ones)
+        cls[:members].each {|m| format_member(m) unless m[:hide] }
+
+        cls
+      end
+
+      # Access to the Img::DirSet object inside doc-formatter
+      def images
+        @formatter.images
+      end
+
+      private
+
+      def format_member(m)
+        @formatter.doc_context = m[:files][0]
+
+        # Turn off type parsing for CSS vars and mixins
+        @formatter.skip_type_parsing = [:css_var, :css_mixin].include?(m[:tagname])
+
+        format_tags(m)
+      end
+
+      def format_tags(context)
+        TagRegistry.html_renderers.each do |tag|
+          if context[tag.tagname]
+            tag.format(context, @formatter)
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/format/doc.rb

@@ -0,0 +1,172 @@
+require 'rubygems'
+require 'strscan'
+require 'rdiscount'
+require 'jsduck/format/html_stack'
+require 'jsduck/format/subproperties'
+require 'jsduck/inline/link'
+require 'jsduck/inline/auto_link'
+require 'jsduck/inline/link_renderer'
+require 'jsduck/inline/img'
+require 'jsduck/inline/video'
+require 'jsduck/inline/example'
+
+module JsDuck
+  module Format
+
+    # Formats doc-comments
+    class Doc
+
+      # Creates a formatter configured with options originating from
+      # command line.  For the actual effect of the options see
+      # Inline::* classes.
+      def initialize(relations={}, opts={})
+        @relations = relations
+        @opts = opts
+        @subproperties = Format::Subproperties.new(self)
+        @link_renderer = Inline::LinkRenderer.new(relations, opts)
+        @inline_link = Inline::Link.new(@link_renderer)
+        @auto_link = Inline::AutoLink.new(@link_renderer)
+        @inline_img = Inline::Img.new(opts)
+        @inline_video = Inline::Video.new(opts)
+        @inline_example = Inline::Example.new(opts)
+        @doc_context = {}
+      end
+
+      # Access to the relations object.
+      # (Used by TypeParser.)
+      attr_reader :relations
+
+      # Accessors to the images attribute of Inline::Img
+      def images=(images)
+        @inline_img.images = images
+      end
+      def images
+        @inline_img.images
+      end
+
+      # Sets up instance to work in context of particular class, so
+      # that when {@link #blah} is encountered it knows that
+      # Context#blah is meant.
+      def class_context=(cls)
+        @inline_link.class_context = cls
+        @auto_link.class_context = cls
+      end
+
+      # Sets up instance to work in context of particular doc object.
+      # Used for error reporting.
+      def doc_context=(doc)
+        @doc_context = doc
+        @inline_video.doc_context = doc
+        @inline_link.doc_context = doc
+        @auto_link.doc_context = doc
+        @inline_img.doc_context = doc
+      end
+
+      # Returns the current documentation context
+      def doc_context
+        @doc_context
+      end
+
+      # Formats doc-comment for placement into HTML.
+      # Renders it with Markdown-formatter and replaces @link-s.
+      def format(input)
+        # In ExtJS source "<pre>" is often at the end of paragraph, not
+        # on its own line.  But in that case RDiscount doesn't recognize
+        # it as the beginning of <pre>-block and goes on parsing it as
+        # normal Markdown, which often causes nested <pre>-blocks.
+        #
+        # To prevent this, we always add extra newline before <pre>.
+        input.gsub!(/([^\n])<pre>/, "\\1\n<pre>")
+
+        # But we remove trailing newline after <pre> to prevent
+        # code-blocks beginning with empty line.
+        input.gsub!(/<pre>(<code>)?\n?/, "<pre>\\1")
+
+        replace(RDiscount.new(input).to_html)
+      end
+
+      # Replaces {@link} and {@img} tags, auto-generates links for
+      # recognized classnames.
+      #
+      # Replaces {@link Class#member link text} in given string with
+      # HTML from @link_tpl.
+      #
+      # Replaces {@img path/to/image.jpg Alt text} with HTML from @img_tpl.
+      #
+      # Adds 'inline-example' class to code examples beginning with @example.
+      #
+      # Additionally replaces strings recognized as ClassNames or
+      # #members with links to these classes or members.  So one doesn't
+      # even need to use the @link tag to create a link.
+      def replace(input)
+        s = StringScanner.new(input)
+        out = ""
+
+        # Keep track of open HTML tags. We're not auto-detecting class
+        # names when inside <a>. Also we want to close down the unclosed
+        # tags.
+        tags = Format::HtmlStack.new(@opts[:ignore_html] || {}, @doc_context)
+
+        while !s.eos? do
+          if substitute = @inline_link.replace(s)
+            out += substitute
+          elsif substitute = @inline_img.replace(s)
+            out += substitute
+          elsif substitute = @inline_video.replace(s)
+            out += substitute
+          elsif s.check(/[{]/)
+            # There might still be "{" that doesn't begin {@link} or {@img} - ignore it
+            out += s.scan(/[{]/)
+          elsif substitute = @inline_example.replace(s)
+            tags.push_tag("pre")
+            tags.push_tag("code")
+            out += substitute
+          elsif s.check(/<\w/)
+            # Open HTML tag
+            out += tags.open(s)
+          elsif s.check(/<\/\w+>/)
+            # Close HTML tag
+            out += tags.close(s)
+          elsif s.check(/</)
+            # Ignore plain '<' char.
+            out += s.scan(/</)
+          else
+            # Replace class names in the following text up to next "<" or "{"
+            # but only when we're not inside <a>...</a>
+            text = s.scan(/[^{<]+/)
+            out += tags.open?("a") ? text : @auto_link.replace(text)
+          end
+        end
+
+        out
+      end
+
+      # Creates a link based on the link template.
+      def link(cls, member, anchor_text, type=nil, static=nil)
+        @link_renderer.link(cls, member, anchor_text, type, static)
+      end
+
+      # Turns type parsing on or off.
+      #
+      # Used to skipping parsing of CSS var and mixin types.
+      def skip_type_parsing=(skip)
+        @subproperties.skip_type_parsing = skip
+      end
+
+      # Recursively formats a subproperty.
+      # See Format::Subproperties#format for details.
+      def format_subproperty(item)
+        @subproperties.format(item)
+      end
+
+      # Parses and formats type definition.
+      # Returns HTML-rendering of the type.
+      # See Format::Subproperties#format_type for details.
+      def format_type(type)
+        @subproperties.format_type(type)
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/format/html_stack.rb

@@ -0,0 +1,109 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Format
+
+    # Tracks opening and closing of HTML tags, with the purpose of
+    # closing down the unfinished tags.
+    #
+    # See Format::Doc#replace for the use of this class.
+    class HtmlStack
+
+      # Initializes the stack with two optional parameters:
+      #
+      # @param ignore_html A hash of additional HTML tags that don't need closing.
+      # @param doc_context Filename and linenr of the current doc-comment.
+      def initialize(ignore_html={}, doc_context={})
+        @ignore_html = ignore_html
+        @doc_context = doc_context
+        @open_tags = []
+      end
+
+      # Scans an opening tag in HTML using the passed in StringScanner.
+      def open(s)
+        s.scan(/</) + push_tag(s.scan(/\w+/)) + s.scan_until(/>|\Z/)
+      end
+
+      # Scans a closing tag in HTML using the passed in StringScanner.
+      def close(s)
+        s.scan(/<\//)
+        tag = s.scan(/\w+/)
+        s.scan(/>/)
+
+        pop_tags(tag).map {|t| "</#{t}>" }.join
+      end
+
+      # Registers opening of a tag.  Returns the tag.
+      def push_tag(tag)
+        @open_tags.push(tag) unless void?(tag)
+        tag
+      end
+
+      # True when the tag is currently open.
+      def open?(tag)
+        @open_tags.include?(tag)
+      end
+
+      private
+
+      # Registers closing of a tag.  Returns all the tags that need to
+      # be closed at that point.
+      def pop_tags(tag)
+        if !@open_tags.include?(tag)
+          if @ignore_html[tag]
+            return [tag]
+          else
+            warn_unopened(tag)
+            return []
+          end
+        end
+
+        popped = []
+        begin
+          popped << t = @open_tags.pop
+          if t != tag
+            warn_unclosed(t)
+          end
+        end until t == tag
+
+        popped
+      end
+
+      def warn_unopened(*tags)
+        warn("Unopened HTML tag", tags)
+      end
+
+      def warn_unclosed(*tags)
+        warn("Unclosed HTML tag", tags)
+      end
+
+      def warn(msg, tags)
+        ctx = @doc_context
+        tag_list = tags.map {|tag| "<#{tag}>" }.join(", ")
+        Logger.warn(:html, "#{msg}: #{tag_list}", ctx[:filename], ctx[:linenr])
+      end
+
+      def void?(tag)
+        VOID_TAGS[tag] || @ignore_html[tag]
+      end
+
+      # Tags that don't require closing
+      VOID_TAGS = {
+        "base" => true,
+        "link" => true,
+        "meta" => true,
+        "hr" => true,
+        "br" => true,
+        "wbr" => true,
+        "area" => true,
+        "img" => true,
+        "param" => true,
+        "input" => true,
+        "isindex" => true,
+        "option" => true,
+      }
+
+    end
+
+  end
+end