Commit 4d3435df authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

Extract #format from Tag#to_html. 

The HTML rendering is now done in two parts:

1. Tag#format method is called, passing the DocFormatter.
   This is where Markdown to HTML conversion happens.

2. Tag#to_html method is called, which must just return HTML.
   No more can formatter be used inside #to_html.

This simplified the passing of DocFormatter instance to Tags -
no more do we need to inject the formatter inside Tag classes,
instead we can just pass it as a parameter.  With this we remove
the single remaining state object from Tag class.
parent 4ae45cb6

lib/jsduck/class_formatter.rb

+3 −13
Original line number Diff line number Diff line
@@ -16,14 +16,6 @@ module JsDuck 
      @relations = relations

      @formatter = formatter

      @include_types = true

      inject_formatter_to_tags

    end



    def inject_formatter_to_tags

      # inject formatter to all html-producing tags

      TagRegistry.html_renderers.each do |tag|

        tag.formatter = @formatter

      end

    end



    # Runs the formatter on doc object of a class.
@@ -35,7 +27,7 @@ module JsDuck 
      cls[:doc] = @formatter.format(cls[:doc]) if cls[:doc]

      # format all members (except hidden ones)

      cls[:members] = cls[:members].map {|m| m[:hide] ? m : format_member(m)  }

      cls[:html_tags] = format_tags_data(cls)

      format_tags_data(cls)

      cls

    end
@@ -61,7 +53,7 @@ module JsDuck 
      m[:return] = format_item(m[:return], is_css_tag) if m[:return]

      m[:throws] = m[:throws].map {|t| format_item(t, is_css_tag) } if m[:throws]

      m[:properties] = m[:properties].map {|b| format_item(b, is_css_tag) } if m[:properties]

      m[:html_tags] = format_tags_data(m)

      format_tags_data(m)

      m

    end
@@ -92,13 +84,11 @@ module JsDuck 
    end



    def format_tags_data(context)

      result = {}

      TagRegistry.html_renderers.each do |tag|

        if context[tag.key]

          result[tag.key] = tag.to_html(context)

          tag.format(context, @formatter)

        end

      end

      result

    end



  end

lib/jsduck/renderer.rb

+4 −4
Original line number Diff line number Diff line
@@ -19,11 +19,11 @@ module JsDuck 
          "<div>",

            render_sidebar,

            "<div class='doc-contents'>",

              render_tags(@cls[:html_tags], :top),

              render_tags(@cls, :top),

              render_private_class_notice,

              @cls[:doc],

              render_enum_class_notice,

              render_tags(@cls[:html_tags], :bottom),

              render_tags(@cls, :bottom),

            "</div>",

            "<div class='members'>",

              render_all_sections,
@@ -247,7 +247,7 @@ module JsDuck 
    def render_long_doc(m)

      doc = []



      doc << render_tags(m[:html_tags], :top)

      doc << render_tags(m, :top)



      doc << m[:doc]
@@ -255,7 +255,7 @@ module JsDuck 
        doc << "<p>Defaults to: <code>" + Util::HTML.escape(m[:default]) + "</code></p>"

      end



      doc << render_tags(m[:html_tags], :bottom)

      doc << render_tags(m, :bottom)



      doc << render_params_and_return(m)

lib/jsduck/tag/deprecated_tag.rb

+5 −1
Original line number Diff line number Diff line
@@ -27,13 +27,17 @@ module JsDuck::Tag 
      h[@key] = v

    end



    def format(context, formatter)

      context[@key][:text] = formatter.format(context[@key][:text])

    end



    def to_html(context)

      depr = context[@key]

      v = depr[:version] ? "since " + depr[:version] : ""

      <<-EOHTML

        <div class='signature-box #{@key}'>

        <p>This #{context[:tagname]} has been <strong>#{@key}</strong> #{v}</p>

        #{format(depr[:text])}

        #{depr[:text]}

        </div>

      EOHTML

    end

lib/jsduck/tag/tag.rb

+9 −10
Original line number Diff line number Diff line
@@ -84,25 +84,24 @@ module JsDuck::Tag 


    # Whether to render the tag before other content (:top) or after

    # it (:bottom).  Must be defined together with #to_html method.

    # Additionally the #format method can be defined to perform

    # rendering of Markdown before #to_html is called.

    attr_accessor :html_position



    # Called before #to_html to allow rendering of Markdown content.

    # For this an instance of DocFormatter is passed in, on which one

    # can call the #format method to turn Markdown into HTML.

    def format(context, formatter)

    end



    # Implement #to_html to transform tag data to HTML to be included

    # into documentation.

    #

    # It gets passed the full class/member hash. It should return an

    # HTML string to inject into document.  For help in that it can

    # use the #format method to easily support Markdown and

    # {@link/img} tags inside the contents.

    # HTML string to inject into document.

    def to_html(context)

    end



    # Helper method for use in #to_html for rendering markdown.

    def format(markdown)

      @formatter.format(markdown)

    end



    attr_accessor :formatter



    # Returns all descendants of JsDuck::Tag::Tag class.

    def self.descendants

      result = []

lib/jsduck/tag_renderer.rb

+9 −6
Original line number Diff line number Diff line
@@ -2,16 +2,19 @@ require 'jsduck/tag_registry' 


module JsDuck



  # Performs the rendering of builtin tags (for now just the signature data).

  # Performs the rendering of tags.

  class TagRenderer

    # Renders tags of a particular section.

    #

    # Returns array of rendered HTML or nil if no tag data.

    def self.render(html_data, position)

      return if html_data.size == 0



    # Takes member or class hash and a position symbol.

    # Returns array of rendered HTML.

    def self.render(member, position)

      TagRegistry.html_renderers(position).map do |tag|

        html_data[tag.key]

        if member[tag.key]

          tag.to_html(member)

        else

          nil

        end

      end

    end