Commit 5ee7be8c authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

Unified links created from {@link}. 

All the links creation is now done inside DocFormatter,
that should ensure they are uniform everywhere.

Added attributes to DocFormatter for tuning it either towards
JSON export or the usual HTML output.

No more using ext:cls and ext:member attributes in HTML,
instead using rel="class#member", which is more standard way.
parent 0e2cf2d5

lib/jsduck/app.rb

+4 −1
Original line number Diff line number Diff line
@@ -133,12 +133,15 @@ module JsDuck 
    # Writes JSON export file for each class

    def write_json(path, relations)

      cache = {}

      formatter = DocFormatter.new

      formatter.cssClass = 'docClass'

      Parallel.each(relations.classes) do |cls|

        filename = path + "/" + cls[:name] + ".json"

        puts "Writing to #{filename} ..." if @verbose

        hash = cls.to_hash

        if hash[:doc]

          hash[:doc] = DocFormatter.new(hash[:name]).format(hash[:doc])

          formatter.context = cls[:name]

          hash[:doc] = formatter.format(hash[:doc])

        end

        json = JSON.pretty_generate(hash)

        File.open(filename, 'w') {|f| f.write(json) }

lib/jsduck/doc_formatter.rb

+26 −9
Original line number Diff line number Diff line
@@ -5,11 +5,23 @@ module JsDuck 


  # Formats doc-comments

  class DocFormatter

    # Initializes instance to work in context of particular class, so

    # CSS class to add to each link

    attr_accessor :cssClass



    # Template for the href URL.

    # Can contain %cls% which is replaced with actual classname.

    # Also '#' and member name is appended to link if needed

    attr_accessor :urlTemplate



    # 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 initialize(context)

      @context = context

    attr_accessor :context



    def initialize

      @context = ""

      @cssClass = nil

      @urlTemplate = "%cls%"

    end



    # Replaces {@link Class#member link text} in given string with
@@ -28,11 +40,6 @@ module JsDuck 
          member = false

        end



        # Construct link attributes

        href = " href=\"output/#{cls}.html" + (member ? "#" + cls + "-" + member : "") + '"'

        ext_cls = ' ext:cls="' + cls + '"'

        ext_member = member ? ' ext:member="' + member + '"' : ""



        # Construct link text

        if text

          text = text
@@ -42,8 +49,18 @@ module JsDuck 
          text = cls

        end



        "<a" + href + ext_cls + ext_member + ">" + text + "</a>"

        link(cls, member, text)

      end

    end



    # Creates HTML link to class and/or member

    def link(cls, member, label)

      anchor = member ? "#" + member : ""

      url = @urlTemplate.sub(/%cls%/, cls) + anchor

      href = ' href="' + url + '"'

      rel = ' rel="' + cls + anchor + '"'

      cssCls = @cssClass ? ' class="' + @cssClass + '"' : ''

      "<a" + href + rel + cssCls + ">" + label + "</a>"

    end



    # Formats doc-comment for placement into HTML.

lib/jsduck/page.rb

+5 −2
Original line number Diff line number Diff line
@@ -19,7 +19,10 @@ module JsDuck 
      @cls = cls

      @relations = relations

      @cache = cache

      @formatter = DocFormatter.new(cls.full_name)

      @formatter = DocFormatter.new

      @formatter.context = cls.full_name

      @formatter.cssClass = 'docClass'

      @formatter.urlTemplate = 'output/%cls%.html'

    end



    def to_html
@@ -62,7 +65,7 @@ module JsDuck 


    def class_link(class_name, label=nil)

      label = label || class_name

      "<a href='output/#{class_name}.html' ext:cls='#{class_name}'>#{label}</a>"

      "<a href='output/#{class_name}.html' class='docClass' rel='#{class_name}'>#{label}</a>"

    end



    def file_link

lib/jsduck/table.rb

+6 −3
Original line number Diff line number Diff line
@@ -20,7 +20,10 @@ module JsDuck 
    def initialize(cls, cache={})

      @cls = cls

      @cache = cache

      @formatter = DocFormatter.new(cls.full_name)

      @formatter = DocFormatter.new

      @formatter.context = cls.full_name

      @formatter.cssClass = 'docClass'

      @formatter.urlTemplate = 'output/%cls%.html'

    end



    def to_html
@@ -78,8 +81,8 @@ module JsDuck 
      cls = item[:member]

      member = item[:name]

      "<a href='output/#{cls}.html##{member}' " +

        "ext:member='##{member}' " +

        "ext:cls='#{cls}'>#{Class.short_name(cls)}</a>"

        "class='docClass' " +

        "rel='#{cls}##{member}'>#{Class.short_name(cls)}</a>"

    end



    def signature(item)

spec/doc_formatter_spec.rb

+4 −4
Original line number Diff line number Diff line
@@ -10,22 +10,22 @@ describe JsDuck::DocFormatter do 


    it "replaces {@link Ext.Msg} with link to class" do

      @formatter.replace("Look at {@link Ext.Msg}").should ==

        'Look at <a href="output/Ext.Msg.html" ext:cls="Ext.Msg">Ext.Msg</a>'

        'Look at <a href="Ext.Msg" rel="Ext.Msg">Ext.Msg</a>'

    end



    it "replaces {@link Foo#bar} with link to class member" do

      @formatter.replace("Look at {@link Foo#bar}").should ==

        'Look at <a href="output/Foo.html#Foo-bar" ext:cls="Foo" ext:member="bar">Foo.bar</a>'

        'Look at <a href="Foo#bar" rel="Foo#bar">Foo.bar</a>'

    end



    it "uses context to replace {@link #bar} with link to class member" do

      @formatter.replace("Look at {@link #bar}").should ==

        'Look at <a href="output/Context.html#Context-bar" ext:cls="Context" ext:member="bar">bar</a>'

        'Look at <a href="Context#bar" rel="Context#bar">bar</a>'

    end



    it "allows use of custom link text" do

      @formatter.replace("Look at {@link Foo link text}").should ==

        'Look at <a href="output/Foo.html" ext:cls="Foo">link text</a>'

        'Look at <a href="Foo" rel="Foo">link text</a>'

    end



    it "leaves text without {@link...} untouched" do