solvas-jsduck 6.0.0.beta.1888

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/render/tags'
+
+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 SCSS vars and mixins
+        @formatter.skip_type_parsing = [:css_var, :css_mixin].include?(m[:tagname])
+
+        format_tags(m)
+      end
+
+      def format_tags(context)
+        Render::Tags.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 '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'
+require 'ostruct'
+
+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=OpenStruct.new)
+        @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>((<code>)?$)/, "\\1\n<pre>\\2")
+
+        # 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.
+      #
+      # Replaces {@img path/to/image.jpg Alt text} with HTML from --img.
+      #
+      # 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 SCSS 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,108 @@
+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)
+        tag_list = tags.map {|tag| "<#{tag}>" }.join(", ")
+        Logger.warn(:html, "#{msg}: #{tag_list}", @doc_context)
+      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

data/lib/jsduck/format/shortener.rb

@@ -0,0 +1,55 @@
+# -*- coding: utf-8 -*-
+require 'jsduck/util/html'
+
+module JsDuck
+  module Format
+
+    # Little helper for shortening text
+    class Shortener
+      # Takes as parameter the maximum length for text that doesn't
+      # get shortened.  Used for testing purposes.
+      def initialize(max_length = 120)
+        @max_length = max_length
+      end
+
+      # Shortens text
+      #
+      # 116 chars is also where ext-doc makes its cut, but unlike
+      # ext-doc we only make the cut when there's more than 120 chars.
+      #
+      # This way we don't get stupid expansions like:
+      #
+      #   Blah blah blah some text...
+      #
+      # expanding to:
+      #
+      #   Blah blah blah some text.
+      #
+      def shorten(input)
+        sent = first_sentence(Util::HTML.strip_tags(input).strip)
+        # Use u-modifier to correctly count multi-byte characters
+        chars = sent.scan(/./mu)
+        if chars.length > @max_length
+          chars[0..(@max_length-4)].join + "..."
+        else
+          sent + " ..."
+        end
+      end
+
+      # Returns the first sentence inside a string.
+      def first_sentence(str)
+        str.sub(/\A(.+?(\.|。))\s.*\z/mu, "\\1")
+      end
+
+      # Returns true when input should get shortened.
+      def too_long?(input)
+        stripped = Util::HTML.strip_tags(input).strip
+        # for sentence v/s full - compare byte length
+        # for full v/s max - compare char length
+        first_sentence(stripped).length < stripped.length || stripped.scan(/./mu).length > @max_length
+      end
+
+    end
+
+  end
+end