Commit 0b8d14f4 authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

Rendering long parameter doc for method. 

Also tuned the expandability detection algorithm.  Now all items
with extra_doc are expandable, and the short version never contains
extra_doc.  Plus the ellipsis is only shown when the primary_doc
is shortened.
parent 08a1007c

lib/jsduck.rb

+1 −0
Original line number Diff line number Diff line
@@ -11,6 +11,7 @@ require 'jsduck/table' 
require 'jsduck/cfg_table'

require 'jsduck/property_table'

require 'jsduck/short_params'

require 'jsduck/long_params'

require 'jsduck/method_table'

require 'jsduck/event_table'

require 'jsduck/page'

lib/jsduck/long_params.rb

0 → 100644
+31 −0
Original line number Diff line number Diff line 
module JsDuck



  # Renders method/event parameters list in long form

  # for use in documentation body.

  class LongParams

    def initialize(cls)

      @links = DocLinks.new(cls.full_name)

    end



    def render(params)

      if params.length > 0

        "<ul>" + params.collect {|p| render_single(p) }.join("") + "</ul>"

      else

        "<ul><li>None.</li></ul>"

      end

    end



    def render_single(param)

      type = param[:type] || "Object"

      name = param[:name] || ""

      doc = @links.replace(param[:doc] || "")

      return [

        "<li>",

        "<code>#{name}</code> : #{type}",

        "<div class='sub-desc'>#{doc}</div>",

        "</li>",

      ].join("")

    end

  end



end

lib/jsduck/method_table.rb

+10 −0
Original line number Diff line number Diff line
@@ -9,6 +9,7 @@ module JsDuck 
      @column_title = "Method"

      @row_class = "method-row"

      @short_params = ShortParams.new

      @long_params = LongParams.new(@cls)

    end



    def signature_suffix(item)
@@ -18,6 +19,15 @@ module JsDuck 
    def return_type(item)

      item[:return] ? (item[:return][:type] || "void") : "void"

    end



    def extra_doc(item)

      [

        "<div class='mdetail-params'>",

        "<strong>Parameters:</strong>",

        @long_params.render(item[:params]),

        "</div>"

      ].join("\n")

    end

  end



end

lib/jsduck/table.rb

+29 −8
Original line number Diff line number Diff line
@@ -3,7 +3,8 @@ module JsDuck 
  # Base class for creating HTML tables of class members.

  #

  # Subclasses must set variables @type, @id, @title, @column_title,

  # @row_class, and implement the signature_suffix() method.

  # @row_class, and implement the signature_suffix() and extra_doc()

  # methods.

  class Table

    def initialize(cls)

      @cls = cls
@@ -27,13 +28,15 @@ module JsDuck 
    end



    def row(item)

      contents = @links.replace(item[:doc])

      expandable = expandable?(contents) ? 'expandable' : ''

      p_doc = primary_doc(item)

      e_doc = extra_doc(item)

      description = expandable_desc(p_doc, e_doc)

      expandable = expandable?(p_doc, e_doc) ? 'expandable' : ''

      inherited = inherited?(item) ? 'inherited' : ''

      [

       "<tr class='#{@row_class} #{expandable} #{inherited}'>",

         "<td class='micon'><a href='#expand' class='exi'>&nbsp;</a></td>",

         "<td class='sig'>#{signature(item)}<div class='mdesc'>#{expandable_desc(contents)}</div></td>",

         "<td class='sig'>#{signature(item)}<div class='mdesc'>#{description}</div></td>",

         "<td class='msource'>#{Class.short_name(item[:member])}</td>",

       "</tr>",

      ].join("")
@@ -56,12 +59,30 @@ module JsDuck 
    #

    #   Blah blah blah some text.

    #

    def expandable_desc(doc)

      expandable?(doc) ? "<div class='short'>#{strip_tags(doc)[0..116]}...</div><div class='long'>#{doc}</div>" : doc

    def expandable_desc(p_doc, e_doc)

      if expandable?(p_doc, e_doc)

        # Only show ellipsis when primary_doc is shortened.

        tagless = strip_tags(p_doc)

        short_doc = tagless[0..116]

        ellipsis = tagless.length > short_doc.length ? "..." : ""

        "<div class='short'>#{short_doc}#{ellipsis}</div>" +

          "<div class='long'>#{p_doc}#{e_doc}</div>"

      else

        p_doc

      end

    end



    def primary_doc(item)

      @links.replace(item[:doc])

    end



    # Override to append extra documentation to the doc found in item[:doc]

    def extra_doc(item)

      ""

    end



    def expandable?(doc)

      strip_tags(doc).length > 120

    def expandable?(p_doc, e_doc)

      strip_tags(p_doc).length > 120 || e_doc.length > 0

    end



    def strip_tags(str)