Commit 3336ce2d authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

Support for auto-generated @since tags. 

The new --old-version option allows one to point JSDuck at doc exports
for different versions.  JSDuck will then import the exported data and
generate @since tags based on that.

For start only classes get @since tags.
parent 60716fba

Rakefile

+4 −0
Original line number Diff line number Diff line
@@ -233,6 +233,10 @@ task :sdk => :sass do 
    "--output", OUT_DIR,

    "--config", "#{SDK_DIR}/extjs/docs/config.json",

    "--examples-base-url", "extjs-build/examples/",

    "--old-version", "2.3.0:compare/ext23",

    "--old-version", "3.4.0:compare/ext34",

    "--old-version", "4.0.7:compare/ext407",

    "--old-version", "4.1.1",

    "--seo",

    "--tests"

  )

lib/jsduck/app.rb

+2 −0
Original line number Diff line number Diff line
@@ -11,6 +11,7 @@ require 'jsduck/logger' 
require 'jsduck/assets'

require 'jsduck/json_duck'

require 'jsduck/io'

require 'jsduck/old_versions'

require 'jsduck/lint'

require 'jsduck/template_dir'

require 'jsduck/class_writer'
@@ -46,6 +47,7 @@ module JsDuck 
      result = aggregate(parsed_files)

      @relations = filter_classes(result)

      InheritDoc.new(@relations).resolve_all

      OldVersions.import(@opts.old_versions, @relations)

      Lint.new(@relations).run



      # Initialize guides, videos, examples, ...

lib/jsduck/old_versions.rb

0 → 100644
+71 −0
Original line number Diff line number Diff line 
require 'jsduck/json_duck'

require 'jsduck/null_object'



module JsDuck



  # Reads in JSDuck exports of different versions of docs.

  module OldVersions

    module_function



    # Loads in exported docs and generates @since tags based on that data.

    def import(versions, relations)

      generate_since_tags(read_all(versions), relations)

    end



    # Reads in data for all versions, returning array of

    # version/class-data pairs.  We don't use a hash to preserve the

    # order of versions (from oldest to newest).

    def read_all(versions)

      versions.map do |ver|

        {

          :version => ver[:version],

          :classes => ver[:path] ? read(ver[:path]) : current_version,

        }

      end

    end



    def current_version

      NullObject.new(:[] => {})

    end



    # Reads in data from all .json files in directory

    def read(path)

      classes = {}

      Dir[path + "/*.json"].each do |filename|

        json = JsonDuck.read(filename)

        classes[json["name"]] = members_id_index(json)

      end

      classes

    end



    # creates index of all class members

    def members_id_index(json)

      index = {}

      ["members", "statics"].each do |group_name|

        json[group_name].each_pair do |tagname, members|

          members.each do |m|

            index[m["id"]] = true

          end

        end

      end

      index

    end



    # Using the imported versions data, adds @since tags to all

    # classes/members.

    def generate_since_tags(versions, relations)

      relations.each do |cls|

        cls[:meta][:since] = available_since(versions, cls[:name])

      end

    end



    # Returns name of the version since which the class is available

    def available_since(versions, class_name)

      versions.each do |ver|

        return ver[:version] if ver[:classes][class_name]

      end

    end



  end



end

lib/jsduck/options.rb

+12 −0
Original line number Diff line number Diff line
@@ -44,6 +44,7 @@ module JsDuck 
    attr_accessor :local_storage_db

    attr_accessor :touch_examples_ui

    attr_accessor :ext_namespaces

    attr_accessor :old_versions



    def initialize

      @input_files = []
@@ -112,6 +113,7 @@ module JsDuck 
      @local_storage_db = "docs"

      @touch_examples_ui = false

      @ext_namespaces = ["Ext"]

      @old_versions = []



      # enable all warnings except :link_auto

      Logger.instance.set_warning(:all, true)
@@ -360,6 +362,16 @@ module JsDuck 
          @ext_namespaces = ns

        end



        opts.on('--old-version=VERSION:PATH',

          "Path to exported docs of specified version.",

          "For the current version, leave the path portion off.", " ") do |v|

          if v =~ /\A(.*?):(.*)\Z/

            @old_versions << {:version => $1, :path => canonical($2)}

          else

            @old_versions << {:version => v}

          end

        end



        opts.on('--config=PATH',

          "Loads config options from JSON file.", " ") do |path|

          path = canonical(path)

lib/jsduck/tag/since.rb

0 → 100644
+26 −0
Original line number Diff line number Diff line 
require "jsduck/meta_tag"

require "jsduck/logger"



module JsDuck::Tag

  # Implementation of @since tag.

  class Since < JsDuck::MetaTag

    def initialize

      @name = "since"

      @key = :since

    end



    def to_value(contents)

      if contents.length > 1

        JsDuck::Logger.instance.warn(nil, "Only one @since tag allowed per class/member.")

      end

      contents[0]

    end



    def to_html(version)

      <<-EOHTML

        <p>Available since: <b>#{version}</b></p>

      EOHTML

    end

  end

end