Change new @option tag formatting

lib/yard/autoload.rb

@@ -104,6 +104,7 @@ module Tags
     autoload :DefaultFactory, 'yard/tags/default_factory'
     autoload :DefaultTag,     'yard/tags/default_tag'
     autoload :Library,        'yard/tags/library'
+    autoload :OptionTag,      'yard/tags/option_tag'
     autoload :RefTag,         'yard/tags/ref_tag'
     autoload :RefTagList,     'yard/tags/ref_tag_list'
     autoload :Tag,            'yard/tags/tag'

lib/yard/generators/base.rb

@@ -64,8 +64,7 @@ def before_list_filters
       # @param [Class] generator 
       #   the generator class to use.
       # 
-      # @option :ignore_serializer [Boolean] (true) whether or not the serializer is ignored.
-      #
+      # @option opts :ignore_serializer [Boolean] (true) whether or not the serializer is ignored.
       # 
       def G(generator, opts = {})
         opts = SymbolHash[:ignore_serializer => true].update(opts)

lib/yard/generators/tags_generator.rb

@@ -5,11 +5,7 @@ class TagsGenerator < Base
       before_section :option, :has_options?
 
       def sections_for(object)
-        [:header, [:param, :option, :yieldparam, :return, :raise, :author, :version, :since, :see]]
-      end
-
-      def param(object)
-        render_tags :param
+        [:header, [:param, :yieldparam, :return, :raise, :author, :version, :since, :see]]
       end
 
       def yieldparam(object)
@@ -50,6 +46,19 @@ def render_tags(name, opts = {})
         opts = { :name => name }.update(opts)
         render(current_object, 'tags', opts)
       end
+
+      def tags_by_param(object)
+        cache = {}
+        [:param, :option].each do |sym|
+          object.tags(sym).each do |t|
+            cache[t.name.to_s] = t
+          end
+        end
+
+        object.parameters.map do |p|
+          cache[p.first.to_s]
+        end.compact
+      end
     end
   end
 end

lib/yard/tags/default_factory.rb

@@ -73,6 +73,11 @@ def parse_tag_with_types_name_and_default(tag_name, text)
         end
       end
 
+      def parse_tag_with_options(tag_name, text)
+        name, text = *extract_name_from_text(text)
+        OptionTag.new(tag_name, name, parse_tag_with_types_name_and_default(tag_name, text))
+      end
+
       private
 
       ##

lib/yard/tags/library.rb

@@ -104,7 +104,7 @@ def initialize(factory = Library.default_factory)
       define_tag "API Visibility",    :api
       define_tag "Todo Item",         :todo,        :with_raw_title_and_text
       define_tag "Example",           :example,     :with_raw_title_and_text
-      define_tag "Options Hash",      :option,      :with_types_name_and_default
+      define_tag "Options Hash",      :option,      :with_options
     end
   end
 end

lib/yard/tags/option_tag.rb

@@ -0,0 +1,12 @@
+module YARD
+  module Tags
+    class OptionTag < Tag
+      attr_accessor :pair
+
+      def initialize(tag_name, name, pair)
+        super(tag_name, nil, nil, name)
+        @pair = pair
+      end
+    end
+  end
+end

spec/tags/default_factory_spec.rb

@@ -109,4 +109,27 @@ def parse_types(text)
     YARD::Tags::DefaultTag.should_receive(:new).with("test", "description", nil, 'NAME', ['default', 'values'])
     parse_types('  NAME (default, values) description')
   end
+end
+
+describe YARD::Tags::DefaultFactory, '#parse_tag_with_options' do
+  before { @f = YARD::Tags::DefaultFactory.new }
+
+  def parse_options(text)
+    @f.parse_tag_with_options('option', text)
+  end
+
+  it "should have a name before tag info" do
+    t = parse_options("xyz key [Types] (default) description")
+    t.tag_name.should == 'option'
+    t.name.should == 'xyz'
+  end
+
+  it "should parse the rest of the tag like DefaultTag" do
+    t = parse_options("xyz key [Types] (default) description")
+    t.pair.should be_instance_of(Tags::DefaultTag)
+    t.pair.types.should == ["Types"]
+    t.pair.name.should == "key"
+    t.pair.defaults.should == ["default"]
+    t.pair.text.should == "description"
+  end
 end

templates/default/tags/html/option.erb

@@ -1,25 +1,27 @@
-<div class="option">
-  <h3>Options Hash:</h3>
-  <table>
-    <tr>
-      <th class="name">Key Name</th>
-      <th class="default">Default Value</th>
-      <th class="type">Accepted Types</th>
-      <th class="desc">Description</th>
-    </tr>
-    <% for tag in object.tags(:option) %>
+<dt>Options Hash <tt><%= param %></tt></dt>
+<dd>
+  <div class="option">
+    <table>
       <tr>
-        <td class="name"><%= tag.name %></td>
-        <td class="default">
-          <% if tag.defaults %>
-            <%= tag.defaults.map {|t| "<tt>#{h t}</tt>" }.join(", ") %>
-          <% else %>
-            <span class="na">N/A</span>
-          <% end %>
-        </td>
-        <td class="type"><%= format_types (tag.types || ['Object']) %></td>
-        <td class="desc"><%= htmlify tag.text %></td>
+        <th class="name">Key Name</th>
+        <th class="default">Default Value</th>
+        <th class="type">Accepted Types</th>
+        <th class="desc">Description</th>
       </tr>
-    <% end %>
-  </table>
-</div>
+      <% for tag in object.tags(:option).select {|x| x.name.to_s == param } %>
+        <tr>
+          <td class="name"><%= tag.pair.name %></td>
+          <td class="default">
+            <% if tag.pair.defaults %>
+              <%= tag.pair.defaults.map {|t| "<tt>#{h t}</tt>" }.join(", ") %>
+            <% else %>
+              <span class="na">N/A</span>
+            <% end %>
+          </td>
+          <td class="type"><%= format_types (tag.pair.types || ['Object']) %></td>
+          <td class="desc"><%= htmlify tag.pair.text %></td>
+        </tr>
+      <% end %>
+    </table>
+  </div>
+</dd>

templates/default/tags/html/param.erb

@@ -0,0 +1,21 @@
+<div class="param">
+  <h3><%= YARD::Tags::Library.labels[:param] %>:</h3>
+  <dl>
+  <% for tag in tags_by_param(object) %>
+    <% if tag.is_a?(YARD::Tags::OptionTag) %>
+      <%= render object, 'option', :param => tag.name.to_s %>
+    <% else %>
+      <dt>
+        <span class='type'><%= format_types (tag.types || ['Object']) %></span>
+        <span class='name'><%= h tag.name %></span>
+        <% if (o=object.parameters.assoc(tag.name.to_sym)) && o[1] %>
+          <em class="default">(defaults to: <tt><%= h o[1] %></tt>)</em>
+        <% end %>
+      </dt>
+      <dd>
+        <span class='desc'><%= htmlify tag.text if tag.text %></span>
+      </dd>
+    <% end %>
+  <% end %>
+  </dl>
+</div>