yard-api 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 199b61a69ee11af6ea6ba0dddb1b7227647258ec
-  data.tar.gz: 7d1e0fec57a1f4366d698c272af0c96056fdf1e7
+  metadata.gz: 4a4a3b1beee6e7ade875e7a95004d14da25fb0d7
+  data.tar.gz: ea2078d3f6d4ecf6afdc91aa635ebf53cb046343
 SHA512:
-  metadata.gz: 412350ca78f192d978a921c57f0a0294e184fe3ce9c754a9e9374a19ba4128deaf0e1f81e98c4f6e2f9599abe07b99d1b53874580c048ae22fdefeb7cbafbe44
-  data.tar.gz: a4ce1b0807cf2e4c5c27aadb4223a28f22a0a96a4a73a0fae2650c36692a5fba2bab480ff42d4f7464a9b51db2b8cbde5e8b33913a517ce72d9c6b9a92d423ac
+  metadata.gz: eeb5f091e4cd539126f6fd69dd93186b9e7ef5ab9f417cf588c25b48fc979585c1b18c4d5bdc0345af656b0d0812c7c7132ef558719622b111c687c85f9e6316
+  data.tar.gz: adb5d639749e0544ef05234636cbe666459a9dc6bfc9fae9c239a25e796ea4539c1b343e4e4a648d81fb8039bd398cb7e0cfc2dd10a14a7b3eb4f288b9944782

data/lib/yard-api/options.rb

@@ -14,6 +14,9 @@ module YARD::APIPlugin
     default_attr :debug, false
     default_attr :theme, 'default'
 
+    default_attr :tabular_arguments, false
+    default_attr :strict_arguments, false
+
     attr_accessor :readme
   end
 end

data/lib/yard-api/tags/argument_tag.rb

@@ -0,0 +1,78 @@
+require 'yaml'
+
+module YARD::APIPlugin::Tags
+  class ArgumentTag < YARD::Tags::Tag
+    attr_reader :accepted_values, :is_required
+
+    RE_ARRAY_LITERAL = /\[[^\]]+\]/
+    RE_ARRAY_TYPE = /^#{RE_ARRAY_LITERAL}$/
+    RE_ACCEPTED_VALUES_PREFIXES = /
+      accepted\svalues |
+      accepts |
+      possible\svalues
+    /imx
+    RE_ACCEPTED_VALUES_STR = /
+      #{RE_ACCEPTED_VALUES_PREFIXES}:\s*(#{RE_ARRAY_LITERAL})
+    /mx
+
+    def initialize(name, buf)
+      YARD::Tags::Library.instance.tag_create(:attr, buf).tap do |tag|
+        super(:argument, tag.text, tag.types, tag.name)
+
+        @is_required = parse_is_required(@types)
+        @accepted_values = parse_accepted_values(@types, @text)
+      end
+    end
+
+    def unscoped_name
+      if scope_tag = @object.tag(:argument_scope)
+        if @name =~ /^#{scope_tag.text}\[([^\]]+)\]$/
+          $1
+        else
+          @name
+        end
+      else
+        @name
+      end
+    end
+
+    private
+
+    def parse_is_required(types)
+      strict = !!YARD::APIPlugin.options.strict_arguments
+      specifier = types.detect { |typestr| typestr.match(/optional|required/i) }
+
+      if specifier
+        types.delete(specifier)
+
+        return true if specifier.downcase == 'required'
+        return false if specifier.downcase == 'optional'
+      end
+
+      strict
+    end
+
+    def parse_accepted_values(types, text)
+      str = if types.last.match(RE_ARRAY_TYPE)
+        types.pop
+      elsif text.match(RE_ACCEPTED_VALUES_STR)
+        $1
+      end
+
+      if str
+        begin
+          YAML.load(str)
+        rescue Exception => e
+          YARD::APIPlugin.on_error <<-Error
+            Unable to parse accepted values for @argument tag.
+            Error: #{exception}
+            Offending docstring:
+            #{text}
+          Error
+
+          return nil
+        end
+      end
+    end
+  end
+end

data/lib/yard-api/tags.rb

@@ -1,5 +1,8 @@
-YARD::Tags::Library.define_tag("API endpiont", :API)
-YARD::Tags::Library.define_tag("API endpiont argument", :argument)
+require 'yard-api/tags/argument_tag'
+
+YARD::Tags::Library.define_tag("API endpoint", :API)
+YARD::Tags::Library.define_tag("API endpoint argument", :argument, YARD::APIPlugin::Tags::ArgumentTag)
+YARD::Tags::Library.define_tag("API endpoint argument scope", :argument_scope)
 YARD::Tags::Library.define_tag("API response field", :request_field)
 YARD::Tags::Library.define_tag("API response field", :response_field)
 YARD::Tags::Library.define_tag("API example request", :example_request, :with_title_and_text)

data/lib/yard-api/version.rb

@@ -1,5 +1,5 @@
 module YARD
   module APIPlugin
-    VERSION = "0.1.3"
+    VERSION = "0.1.4"
   end
 end

data/lib/yard-api.rb

@@ -31,6 +31,19 @@ module YARD
     def self.options
       @@options ||= Options.new
     end
+
+    def self.log(message, level=::Logger::INFO)
+      log = YARD::Logger.instance
+      log.enter_level(level) { log.puts(message) }
+    end
+
+    def self.on_error(message)
+      if self.options.strict
+        raise error
+      else
+        self.log(error, ::Logger::WARN)
+      end
+    end
   end
 
   require 'yard-api/version'

data/spec/spec_helper.rb

@@ -1,44 +1,113 @@
-#
-# Copyright (c) 2013 Instructure, Inc.
-#
-# Permission is hereby granted, free of charge, to any person obtaining a
-# copy of this software and associated documentation files (the "Software"),
-# to deal in the Software without restriction, including without limitation
-# the rights to use, copy, modify, merge, publish, distribute, sublicense,
-# and/or sell copies of the Software, and to permit persons to whom the
-# Software is furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
-# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
-#
-
-require 'yard'
-require File.join(File.dirname(__FILE__), '..', 'lib', 'yard-api')
-
 # This file was generated by the `rspec --init` command. Conventionally, all
 # specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
-# Require this file using `require "spec_helper"` to ensure that it is only
-# loaded once.
+# The generated `.rspec` file contains `--require spec_helper` which will cause this
+# file to always be loaded, without a need to explicitly require it in any files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, consider making
+# a separate helper file that requires the additional dependencies and performs
+# the additional setup, and require it from the spec files that actually need it.
+#
+# The `.rspec` file also contains a few flags that are not defaults but that
+# users commonly want.
 #
 # See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
 RSpec.configure do |config|
-  config.treat_symbols_as_metadata_keys_with_true_values = true
-  config.run_all_when_everything_filtered = true
+
+  require File.join(File.dirname(__FILE__), '..', 'lib', 'yard-api')
+
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    # be_bigger_than(2).and_smaller_than(4).description
+    #   # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #   # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+# The settings below are suggested to provide a good initial experience
+# with RSpec, but feel free to customize to your heart's content.
+=begin
+  # These two settings work together to allow you to limit a spec run
+  # to individual examples or groups you care about by tagging them with
+  # `:focus` metadata. When nothing is tagged with `:focus`, all examples
+  # get run.
   config.filter_run :focus
+  config.run_all_when_everything_filtered = true
+
+  # Limits the available syntax to the non-monkey patched syntax that is recommended.
+  # For more details, see:
+  #   - http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax
+  #   - http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   - http://myronmars.to/n/dev-blog/2014/05/notable-changes-in-rspec-3#new__config_option_to_disable_rspeccore_monkey_patching
+  config.disable_monkey_patching!
+
+  # This setting enables warnings. It's recommended, but in some cases may
+  # be too noisy due to issues in dependencies.
+  config.warnings = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = 'doc'
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  config.profile_examples = 10
 
   # Run specs in random order to surface order dependencies. If you find an
   # order dependency and want to debug it, you can fix the order by providing
   # the seed, which is printed after each run.
   #     --seed 1234
-  config.order = 'random'
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+=end
+
+  config.before(:each) do
+    @overridden_options = {}
+    @options = YARD::APIPlugin.options
+  end
+
+  def set_option(key, value)
+    unless @overridden_options.has_key?(key.to_sym)
+      @overridden_options[key.to_sym] = @options.value
+    end
+
+    @options.send("#{key}=", value)
+  end
+
+  config.after(:each) do
+    @overridden_options.each_pair do |key, value|
+      @options.send("#{key}=", value)
+    end
 
-  include YARD
+    @overridden_options.clear
+  end
 end

data/spec/tags/argument_spec.rb

@@ -0,0 +1,129 @@
+require 'spec_helper'
+
+describe YARD::APIPlugin::Tags::ArgumentTag do
+  def populate(str=nil)
+    YARD::Registry.clear
+    YARD.parse_string str if str
+  end
+
+  def find_tag(method_name, tag_name, index=0)
+    P(method_name.to_sym)
+      .tags.select { |tag| tag.tag_name == tag_name.to_s }[index]
+  end
+
+  before do
+    YARD::Registry.clear
+  end
+
+  it 'should work like an @attr tag' do
+    populate <<-'eof'
+      # @argument [String] name
+      #   Your full name.
+      def signup
+      end
+    eof
+
+    tag = find_tag(:signup, :argument, 0)
+
+    expect(tag.name).to eq 'name'
+    expect(tag.text).to eq 'Your full name.'
+    expect(tag.types).to eq ['String']
+  end
+
+  describe '#is_required' do
+    it 'should default to whatever Options.strict_arguments is set to' do
+      set_option(:strict_arguments, false)
+
+      populate <<-'eof'
+        # @argument [String] name
+        #   Your full name.
+        #
+        # @argument [Optional, Number] age
+        #   How old you currently are.
+        def signup
+        end
+      eof
+
+      expect(find_tag(:signup, :argument, 0).is_required).to be false
+      expect(find_tag(:signup, :argument, 1).is_required).to be false
+
+      set_option(:strict_arguments, true)
+
+      populate <<-'eof'
+        # @argument [String] name
+        #   Your full name.
+        #
+        # @argument [Optional, Number] age
+        #   How old you currently are.
+        def signup
+        end
+      eof
+
+      expect(find_tag(:signup, :argument, 0).is_required).to be true
+      expect(find_tag(:signup, :argument, 1).is_required).to be false
+    end
+
+    it 'should be true if Required is written in typestr' do
+      set_option :strict_arguments, false
+
+      populate <<-'eof'
+        # @argument [Required, String] name
+        #   Your full name.
+        def signup
+        end
+      eof
+
+      expect(find_tag(:signup, :argument).is_required).to be true
+    end
+  end
+
+  describe '#accepted_values' do
+    it 'should work in the type specifier: @argument [String, ["foo", "bar"]]' do
+      populate <<-'eof'
+        # @argument [Required, String, ["S","M","L","XL"]] size
+        #   Your full name.
+        def order_shirt
+        end
+      eof
+
+      expect(find_tag(:order_shirt, :argument).accepted_values).to eq(%w[S M L XL])
+    end
+
+    it 'should work using "Accepted values: [...]"' do
+      populate <<-'eof'
+        # @argument [String] size
+        #   Size of the t-shirt you want.
+        #   Accepted values: ["S","M","L","XL"]
+        def order_shirt
+        end
+      eof
+
+      expect(find_tag(:order_shirt, :argument).accepted_values).to eq(%w[S M L XL])
+    end
+
+    it 'should work using "Accepts: [...]"' do
+      populate <<-'eof'
+        # @argument [String] size
+        #   Size of the t-shirt you want.
+        #   Accepts: ["S","M","L","XL"]
+        def order_shirt
+        end
+      eof
+
+      expect(find_tag(:order_shirt, :argument).accepted_values).to eq(%w[S M L XL])
+    end
+
+    it 'should work using "Possible values: [...]"' do
+      populate <<-'eof'
+        # @argument [String] size
+        #   Size of the t-shirt you want.
+        #   Possible values: ["S","M","L","XL"]
+        def order_shirt
+        end
+      eof
+
+      expect(find_tag(:order_shirt, :argument).accepted_values).to eq(%w[S M L XL])
+    end
+
+  end
+end

data/templates/api/fulldoc/html/setup.rb

@@ -10,6 +10,11 @@ def init
 
   build_json_objects_map
   generate_assets
+
+  if api_options.one_file
+    return serialize_onefile_index
+  end
+
   serialize_index
   serialize_static_pages
   serialize_resource_index if api_options['resource_index']
@@ -38,8 +43,6 @@ def serialize_resource(resource, controllers)
 end
 
 def serialize_index
-  return serialize_onefile_index if api_options.one_file
-
   options[:file] = api_options['readme']
   serialize('index.html')
   options.delete(:file)

data/templates/api/tags/html/argument/_list.erb

@@ -0,0 +1,29 @@
+<ul class="argument">
+  <% @argument_tags.each do |tag| %>
+    <%
+      tag.text ||= ''
+      desc = tag.text.strip.sub(/^\[([^\]]+)\]/, '').strip
+      type = $1
+      desc = desc.sub(/(\(optional\))/, '').strip
+      is_optional = $1.present?
+      name, desc = desc.split(/\s/, 2).map(&:strip)
+      desc = desc.sub(/[A|a]ccepted values:\s*\[([^\]]+)\]/, '').strip
+      accepted_values = $1
+    %>
+    <li>
+      <code class="argument-name"><%= h name %></code>
+      <span class="argument-type"><%= type %></span>
+      <span class="argument-values fade">
+        <em><%= "[#{accepted_values}]" if accepted_values.present? %></em>
+      </span>
+
+      <% unless is_optional %>
+        <em class="argument-required">Required</em>
+      <% end %>
+
+      <% if !desc.empty? %>
+        <%= html_markup_markdown(desc) %>
+      <% end %>
+    </li>
+  <% end %>
+</ul>

data/templates/api/tags/html/argument/_table.erb

@@ -0,0 +1,41 @@
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Type</th>
+      <th>Accepted Values</th>
+      <th>Required?</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+
+  <tbody>
+    <% @argument_tags.each do |tag| %>
+      <tr>
+        <td><code class="argument-name"><%= h tag.unscoped_name %></code></td>
+        <td><span class="argument-type"><%= tag.type %></span></td>
+        <td>
+          <ul class="argument-values">
+            <% (tag.accepted_values || []).each do |value| %>
+              <li><%= value %></li>
+            <% end %>
+          </ul>
+        </td>
+
+        <td>
+          <% if tag.is_required %>
+            <em class="argument-required">Yes</em>
+          <% else %>
+            <em class="argument-optional">No</em>
+          <% end %>
+        </td>
+
+        <td>
+          <% if !tag.text.empty? %>
+            <%= html_markup_markdown(tag.text) %>
+          <% end %>
+        </td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>

data/templates/api/tags/html/argument.erb

@@ -1,32 +1,9 @@
 <section class="endpoint-arguments">
   <h4>Parameters:</h4>
-  <ul class="argument">
-    <% @argument_tags.each do |tag| %>
-      <%
-        tag.text ||= ''
-        desc = tag.text.strip.sub(/^\[([^\]]+)\]/, '').strip
-        type = $1
-        desc = desc.sub(/(\(optional\))/, '').strip
-        is_optional = $1.present?
-        name, desc = desc.split(/\s/, 2).map(&:strip)
-        desc = desc.sub(/[A|a]ccepted values:\s*\[([^\]]+)\]/, '').strip
-        accepted_values = $1
-      %>
-      <li>
-        <code class="argument-name"><%= h name %></code>
-        <span class="argument-type"><%= type %></span>
-        <span class="argument-values fade">
-          <em><%= "[#{accepted_values}]" if accepted_values.present? %></em>
-        </span>
 
-        <% unless is_optional %>
-          <em class="argument-required">Required</em>
-        <% end %>
-
-        <% if !desc.empty? %>
-          <%= html_markup_markdown(desc) %>
-        <% end %>
-      </li>
-    <% end %>
-  </ul>
+  <% if api_options.tabular_arguments %>
+    <%= erb :"argument/_table" %>
+  <% else %>
+    <%= erb :"argument/_list" %>
+  <% end %>
 </section>

data/yard-api.gemspec

@@ -17,6 +17,6 @@ Gem::Specification.new do |s|
   s.license     = 'AGPL3'
   s.add_dependency 'yard', '0.8.7'
   s.add_dependency 'yard-appendix', '~> 0.1.8'
-  s.add_development_dependency 'rspec', '~> 0'
-  s.add_development_dependency 'gem-release', '~> 0'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'gem-release'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yard-api
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Ahmad Amireh
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-14 00:00:00.000000000 Z
+date: 2014-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -42,28 +42,28 @@ dependencies:
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: gem-release
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: |2
@@ -81,6 +81,7 @@ files:
 - lib/yard-api/options.rb
 - lib/yard-api/railtie.rb
 - lib/yard-api/tags.rb
+- lib/yard-api/tags/argument_tag.rb
 - lib/yard-api/templates/helpers/base_helper.rb
 - lib/yard-api/templates/helpers/html_helper.rb
 - lib/yard-api/templates/helpers/route_helper.rb
@@ -88,6 +89,7 @@ files:
 - lib/yard-api/version.rb
 - lib/yard-api/yardoc_task.rb
 - spec/spec_helper.rb
+- spec/tags/argument_spec.rb
 - tasks/yard_api.rake
 - templates/api/appendix/html/setup.rb
 - templates/api/docstring/html/setup.rb
@@ -106,6 +108,8 @@ files:
 - templates/api/onefile/html/sidebar.erb
 - templates/api/tags/html/_example_code_block.erb
 - templates/api/tags/html/argument.erb
+- templates/api/tags/html/argument/_list.erb
+- templates/api/tags/html/argument/_table.erb
 - templates/api/tags/html/emits.erb
 - templates/api/tags/html/example_request.erb
 - templates/api/tags/html/example_response.erb