Commit e7add9b1 authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

New extensible meta tags. 

Each meta-tag is now implemented as a class.  The --meta-tags option
specifies a path to Ruby file that contains the implementations.

By default the sencha_tags.rb file is included which implements
@author and @docauthor as hidden tags.
parent 1768d023

lib/jsduck/app.rb

+4 −1
Original line number Diff line number Diff line
@@ -159,6 +159,9 @@ module JsDuck 
      class_formatter = ClassFormatter.new(@relations, doc_formatter)

      # Don't format types when exporting

      class_formatter.include_types = !@opts.export

      # Inject formatter to all meta-tags.

      @opts.meta_tags.each {|tag| tag.formatter = doc_formatter }

      class_formatter.meta_tags = @opts.meta_tags

      # Format all doc-objects in parallel

      formatted_classes = @parallel.map(@relations.classes) do |cls|

        {
@@ -188,7 +191,7 @@ module JsDuck 
    # Writes JSON export or JsonP file for each class

    def write_classes

      exporter = Exporter.new(@relations)

      renderer = Renderer.new(@opts)

      renderer = Renderer.new

      dir = @opts.output_dir + (@opts.export ? "" : "/output")

      @parallel.each(@relations.classes) do |cls|

        filename = dir + "/" + cls[:name] + (@opts.export ? ".json" : ".js")

lib/jsduck/class_formatter.rb

+13 −0
Original line number Diff line number Diff line
@@ -9,11 +9,14 @@ module JsDuck 
  class ClassFormatter

    # Set to false to disable HTML-formatting of type definitions.

    attr_accessor :include_types

    # List of meta-tag implementations

    attr_accessor :meta_tags



    def initialize(relations, formatter)

      @relations = relations

      @formatter = formatter

      @include_types = true

      @meta_tags = []

    end



    # Runs the formatter on doc object of a class.
@@ -29,9 +32,19 @@ module JsDuck 
      cls[:statics].each_pair do |type, members|

        cls[:statics][type] = members.reject {|m| m[:private] }.map {|m| format_member(m) }

      end

      cls[:meta] = cls[:meta].map {|m| format_meta(m) }.compact

      cls

    end



    def format_meta(meta)

      tag = @meta_tags.find {|tag| tag.name == meta[:name] }

      if tag.hidden

        nil

      else

        {:name => tag.name, :title => tag.title, :content => tag.transform(meta[:content])}

      end

    end



    def format_member(m)

      @formatter.doc_context = m

      m[:doc] = @formatter.format(m[:doc]) if m[:doc]

lib/jsduck/doc_parser.rb

+3 −2
Original line number Diff line number Diff line
@@ -30,7 +30,7 @@ module JsDuck 


      @meta_tags_map = {}

      (meta_tags || []).each do |tag|

        @meta_tags_map[tag[:name]] = true

        @meta_tags_map[tag.name] = tag

      end

    end
@@ -146,7 +146,8 @@ module JsDuck 
          boolean_at_tag(/@abstract/, :abstract)

        elsif look(/@/)

          @input.scan(/@/)

          if @meta_tags_map[look(/\w+/)]

          meta_tag = @meta_tags_map[look(/\w+/)]

          if meta_tag

            add_tag(:meta)

            @current_tag[:name] = match(/\w+/)

            skip_horiz_white

lib/jsduck/meta_tag.rb

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



  # Abstract base class for all meta tag implementations.

  #

  # Child classes must define value for @name attribute.  They can

  # also provide @title, @hidden, and override #render method.

  class MetaTag

    # Name of the tag (required)

    attr_reader :name



    # Title to use when rendering the meta-tag info

    attr_reader :title



    # True to not render the meta tag at all

    attr_reader :hidden



    # Override this to transform the content of meta-tag in whichever

    # way desired.

    def transform(text)

      markdown(text)

    end



    # This is used to inject the formatter object for #markdown method

    attr_accessor :formatter



    # Helper method to format the text

    def markdown(text)

      @formatter.format(text)

    end



    # Returns all descendants of MetaTag class.

    def self.descendants

      result = []

      ObjectSpace.each_object(::Class) do |cls|

        result << cls if cls < self

      end

      result

    end



  end



end

lib/jsduck/options.rb

+13 −11
Original line number Diff line number Diff line 
require 'optparse'

require 'jsduck/meta_tag'



module JsDuck
@@ -68,10 +69,8 @@ module JsDuck 
        # Special anything-goes type

        "Mixed",

      ]

      @meta_tags = [

        {:name => "author", :title => "Author", :strip => / *<.*?> */},

        {:name => "docauthor", :title => "Documentation author", :strip => / *<.*?> */},

      ]

      @meta_tags = []

      @meta_tags_path = File.dirname(__FILE__) + "/sencha_tags"



      @warnings = true

      @verbose = false
@@ -117,6 +116,12 @@ module JsDuck 
    def parse!(argv)

      create_option_parser.parse!(argv).each {|fname| read_filenames(fname) }

      validate

      # Instanciate all loaded MetaTag implementations

      require @meta_tags_path

      @meta_tags = []

      MetaTag.descendants.each do |cls|

        @meta_tags << cls.new

      end

    end



    def create_option_parser
@@ -145,13 +150,10 @@ module JsDuck 
          read_filenames(@root_dir + "/js-classes")

        end



        opts.on('--meta-tags @name=Title,...', Array,

          "Defines custom meta-data tags in addition to",

          "@author and @docauthor.  Experimantal!", " ") do |tags|

          tags.each do |t|

            t = t.split(/=/)

            @meta_tags << {:name => t[0].sub(/^@/, ""), :title => t[1]}

          end

        opts.on('--meta-tags=PATH',

          "Path to Ruby file with custom meta-tag implementations.",

          "Experimantal!", " ") do |path|

          @meta_tags_path = path

        end



        opts.on('--no-warnings', "Turns off warnings.", " ") do