yard-api 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2f85c9b29ec43288a01d9a3a1da6dc98efe4edba
-  data.tar.gz: 71062272d43be57a50ef1044588f15e4ec79a290
+  metadata.gz: 2f894b7c9e0efdee454a068de0105e061b713784
+  data.tar.gz: a5eb169d8372bcea684866395a2a4ecddda65385
 SHA512:
-  metadata.gz: f67b6fcd65e95be498ccfed4847222d5cae3365c2e75f3c648fc6b6ad5b4aeebace9bf951d72b77379f81f506b6c578e138c2521719a7225aa86dfac678a5094
-  data.tar.gz: 6cb625748831b6d18fb3cc631750ba2eed5f0f6436aeeb5071e98644cc7e54190609b52e8026dd74966da870ebad6abe72d2e2dfe6bcda13da4cb8c0cf21b9a0
+  metadata.gz: 297b3d21420a0a60052d77f4d2748ed252e32298e78b3e87d2b7f13f6229efe389483b52bc4f309399b87eb5b816befe0f91c7be4fa479aa81f383890b453479
+  data.tar.gz: fea346e1cee3d55253920f2fba306f797a5a86c41e74418e42958ace2d96dd2269499808df1f345080716f002ee4afd8816c93686cec1b9235e1d1459e9d7cc0

data/README.md

@@ -8,6 +8,22 @@ TODO
 
 TODO
 
+### Compatibility options
+
+#### `@argument` tags with names specified before types
+
+For tags that have a type and a name such as the YARD `@attr` tag, or the yard-api `@argument` tag, the "correct" syntax is to specify the types *before* the name. For example:
+
+```ruby
+# @argument [String] name
+#   This is compliant with YARD syntax.
+#
+# @argument name [String]
+#   This is not compliant with YARD syntax.
+```
+
+If your project already uses the (incorrect) second syntax and you would like to keep things that way, then you can use the compatibility option `leading_argument_name_fix` to have yard-api correctify this and understand both flavors.
+
 ## Configuration
 
 `yard-api` will look for a file in `config/yard_api.yml` in the Rails root for customizations. Configuration fields not specified in that file will be filled with the default values found in [config/yard_api.yml](https://github.com/amireh/yard-api/blob/master/config/yard_api.yml).
@@ -20,6 +36,10 @@ Read that file to view all the available options.
 
 ## Changelog
 
+**0.1.7**
+
+- new compatibility option `leading_argument_name_fix`
+
 **15/9/2014**
 
 - `@argument` tags can now be formatted in a table by setting the `tabular_arguments` option to true

data/config/yard_api.yml

@@ -83,4 +83,18 @@ sidebar_width: 240
 content_width: "fluid"
 
 # Whitespace between the Sidebar and the content, in pixels.
-spacer: 20
+spacer: 20
+
+# Compatibility option.
+#
+# If your project (mis)uses the @argument tag to specify the name before the
+# types, e.g `@argument name [String]`, then turn this on and yard-api will
+# make these docstrings compliant with YARD's @attr tag (or any tag with a name
+# and a type, really) which is what @argument uses as its back-end tag.
+#
+# The "right" thing to do is to use the correct YARD syntax:
+#
+#   @argument [Type specifier] name_specifier
+#
+# But that may not be viable in very large, existing projects.
+leading_argument_name_fix: false

data/lib/yard-api/options.rb

@@ -26,6 +26,8 @@ module YARD::APIPlugin
     default_attr :content_width, 'fluid'
     default_attr :spacer, 20
 
+    default_attr :leading_argument_name_fix, false
+
     attr_accessor :readme
   end
 end

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

@@ -4,6 +4,7 @@ module YARD::APIPlugin::Tags
   class ArgumentTag < YARD::Tags::Tag
     attr_reader :accepted_values, :is_required
 
+    RE_NAME = /^([\S]+)/
     RE_ARRAY_LITERAL = /\[[^\]]+\]/
     RE_ARRAY_TYPE = /^#{RE_ARRAY_LITERAL}$/
     RE_ACCEPTED_VALUES_PREFIXES = /
@@ -16,8 +17,26 @@ module YARD::APIPlugin::Tags
     /mx
 
     def initialize(name, buf)
+      name = nil
+
+      # If the name specifier is written before the types and contains brackets,
+      # YARD will not properly parse the attributes (it doesn't even say that it
+      # supports this syntax so), something like this:
+      #
+      #   @argument shirt[size] [String]
+      #
+      # We convert the name to use underscores instead and YARD does its magic!
+      # Once the tag is parsed, we'll use the original name.
+      #
+      # @since 0.1.7
+      if buf[0] != '[' && YARD::APIPlugin.options.leading_argument_name_fix
+        arg_name = buf.match(RE_NAME).captures.first
+        buf.sub!(arg_name, arg_name.gsub(/\W/, '_'))
+        name = arg_name
+      end
+
       YARD::Tags::Library.instance.tag_create(:attr, buf).tap do |tag|
-        super(:argument, tag.text, tag.types, tag.name)
+        super(:argument, tag.text, tag.types, name || tag.name)
 
         @is_required = parse_is_required(@types)
         @accepted_values = parse_accepted_values(@types, @text)

data/lib/yard-api/version.rb

@@ -1,5 +1,5 @@
 module YARD
   module APIPlugin
-    VERSION = "0.1.8"
+    VERSION = "0.1.10"
   end
 end

data/spec/tags/argument_spec.rb

@@ -16,6 +16,7 @@ describe YARD::APIPlugin::Tags::ArgumentTag do
   end
 
   it 'should work like an @attr tag' do
+        ENV['DO'] = '1'
     populate <<-'eof'
       # @argument [String] name
       #   Your full name.
@@ -30,6 +31,46 @@ describe YARD::APIPlugin::Tags::ArgumentTag do
     expect(tag.types).to eq ['String']
   end
 
+  describe 'option: leading_argument_name_fix' do
+    it 'should work with type and name specifiers swapped "@argument name [String]"' do
+      set_option(:leading_argument_name_fix, true)
+
+      populate <<-'eof'
+        # @argument name [String]
+        #   Your full name.
+        #
+        # @argument shirt_size [String, ["S", "M", "L"]]
+        #   Size of the shirt you wear.
+        #
+        # @argument shirt[size] [String, ["S", "M", "L"]]
+        #   Size of the shirt you wear.
+        #
+        def signup
+        end
+      eof
+
+      find_tag(:signup, :argument, 0).tap do |tag|
+        expect(tag.name).to eq 'name'
+        expect(tag.text).to eq 'Your full name.'
+        expect(tag.types).to eq ['String']
+      end
+
+      find_tag(:signup, :argument, 1).tap do |tag|
+        expect(tag.name).to eq 'shirt_size'
+        expect(tag.text).to eq 'Size of the shirt you wear.'
+        expect(tag.types).to eq ['String']
+        expect(tag.accepted_values).to eq %w[ S M L ]
+      end
+
+      find_tag(:signup, :argument, 2).tap do |tag|
+        expect(tag.name).to eq 'shirt[size]'
+        expect(tag.text).to eq 'Size of the shirt you wear.'
+        expect(tag.types).to eq ['String']
+        expect(tag.accepted_values).to eq %w[ S M L ]
+      end
+    end
+  end
+
   describe '#is_required' do
     it 'should default to whatever Options.strict_arguments is set to' do
       set_option(:strict_arguments, false)
@@ -124,6 +165,5 @@ describe YARD::APIPlugin::Tags::ArgumentTag do
 
       expect(find_tag(:order_shirt, :argument).accepted_values).to eq(%w[S M L XL])
     end
-
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yard-api
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.10
 platform: ruby
 authors:
 - Ahmad Amireh
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-15 00:00:00.000000000 Z
+date: 2014-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -97,6 +97,7 @@ files:
 - templates/api/docstring/html/text.erb
 - templates/api/fulldoc/html/css/common.css
 - templates/api/fulldoc/html/css/highlight.css
+- templates/api/fulldoc/html/js/highlight.zip
 - templates/api/fulldoc/html/js/highlight/CHANGES.md
 - templates/api/fulldoc/html/js/highlight/LICENSE
 - templates/api/fulldoc/html/js/highlight/README.md