From fda20f3c11b998b4de05f5b90ed2c621030da984 Mon Sep 17 00:00:00 2001
From: Rene Saarsoo <nene@triin.net>
Date: Tue, 5 Jun 2012 13:10:27 +0300
Subject: [PATCH] Implement @throws as builtin tag.

---
 lib/jsduck/class_formatter.rb  |  1 +
 lib/jsduck/doc_parser.rb       | 10 ++++++++
 lib/jsduck/merger.rb           | 12 +++++++++
 lib/jsduck/renderer.rb         | 20 +++++++++++++++
 lib/jsduck/tag/throws.rb       | 46 ----------------------------------
 spec/aggregator_throws_spec.rb | 12 ++++-----
 6 files changed, 49 insertions(+), 52 deletions(-)
 delete mode 100644 lib/jsduck/tag/throws.rb

diff --git a/lib/jsduck/class_formatter.rb b/lib/jsduck/class_formatter.rb
index 6b3d8cc5..43c5e310 100644
--- a/lib/jsduck/class_formatter.rb
+++ b/lib/jsduck/class_formatter.rb
@@ -48,6 +48,7 @@ module JsDuck
       m[:html_type] = (@include_types && !is_css_tag) ? format_type(m[:type]) : m[:type] if m[:type]
       m[:params] = m[:params].map {|p| format_item(p, is_css_tag) } if m[:params]
       m[:return] = format_item(m[:return], is_css_tag) if m[:return]
+      m[:throws] = m[:throws].map {|t| format_item(t, is_css_tag) } if m[:throws]
       m[:properties] = m[:properties].map {|b| format_item(b, is_css_tag) } if m[:properties]
       m[:html_meta] = format_meta_data(m)
       m
diff --git a/lib/jsduck/doc_parser.rb b/lib/jsduck/doc_parser.rb
index 5a639ee1..1e9c6e38 100644
--- a/lib/jsduck/doc_parser.rb
+++ b/lib/jsduck/doc_parser.rb
@@ -132,6 +132,8 @@ module JsDuck
           at_alias
         elsif look(/@var\b/)
           at_var
+        elsif look(/@throws\b/)
+          at_throws
         elsif look(/@inheritable\b/)
           boolean_at_tag(/@inheritable/, :inheritable)
         elsif look(/@accessor\b/)
@@ -276,6 +278,14 @@ module JsDuck
       skip_white
     end
 
+    # matches @throws {type} ...
+    def at_throws
+      match(/@throws/)
+      add_tag(:throws)
+      maybe_type
+      skip_white
+    end
+
     # matches @type {type}  or  @type type
     #
     # The presence of @type implies that we are dealing with property.
diff --git a/lib/jsduck/merger.rb b/lib/jsduck/merger.rb
index 999107ab..ac54bc2e 100644
--- a/lib/jsduck/merger.rb
+++ b/lib/jsduck/merger.rb
@@ -162,6 +162,7 @@ module JsDuck
         :doc => detect_doc(docs),
         :params => detect_params(:method, doc_map, code),
         :return => detect_return(doc_map, name == "constructor" ? "Object" : "undefined"),
+        :throws => detect_throws(doc_map),
       }, doc_map)
     end
 
@@ -477,6 +478,17 @@ module JsDuck
       }
     end
 
+    def detect_throws(doc_map)
+      return unless doc_map[:throws]
+
+      doc_map[:throws].map do |throws|
+        {
+          :type => throws[:type] || "Object",
+          :doc => throws[:doc] || "",
+        }
+      end
+    end
+
     # Combines :doc-s of most tags
     # Ignores tags that have doc comment themselves and subproperty tags
     def detect_doc(docs)
diff --git a/lib/jsduck/renderer.rb b/lib/jsduck/renderer.rb
index f0ea108b..844d84a6 100644
--- a/lib/jsduck/renderer.rb
+++ b/lib/jsduck/renderer.rb
@@ -318,6 +318,10 @@ module JsDuck
         doc << render_return(ret)
       end
 
+      if item[:throws]
+        doc << render_throws(item[:throws])
+      end
+
       doc
     end
 
@@ -351,6 +355,22 @@ module JsDuck
         "</ul>",
       ]
     end
+
+    def render_throws(throws)
+      return [
+        "<h3 class='pa'>Throws</h3>",
+        "<ul>",
+          throws.map do |thr|
+            [
+              "<li>",
+                "<span class='pre'>#{thr[:html_type]}</span>",
+                "<div class='sub-desc'>#{thr[:doc]}</div>",
+              "</li>",
+            ]
+          end,
+        "</ul>",
+      ]
+    end
   end
 
 end
diff --git a/lib/jsduck/tag/throws.rb b/lib/jsduck/tag/throws.rb
deleted file mode 100644
index b3176bd9..00000000
--- a/lib/jsduck/tag/throws.rb
+++ /dev/null
@@ -1,46 +0,0 @@
-require "jsduck/meta_tag"
-require "jsduck/logger"
-
-module JsDuck::Tag
-  class Throws < JsDuck::MetaTag
-    def initialize
-      @name = "throws"
-      @key = :throws
-      @signature = {:long => "throws", :short => "THR"}
-      @multiline = true
-    end
-
-    def to_value(tags)
-      tags.map do | throws |
-        if throws =~ /\A\{([\w\.]+)\}\s+([^ ].*)\Z/m
-          {:type => $1, :doc => $2.strip}
-        else
-          {:type => "Object", :doc => throws}
-        end
-      end
-    end
-
-    def to_html(values)
-      return if values.length == 0
-
-      html = values.map do | throws |
-        <<-EOHTML
-          <li>
-            <span class="pre"><a href="#!/api/#{throws[:type]}">#{throws[:type]}</a></span>
-            <div class="sub-desc">
-              <p>#{throws[:doc]}</p>
-            </div>
-          </li>
-        EOHTML
-      end.join
-
-      return <<-EOHTML
-        <h3>Throws</h3>
-        <ul>
-          #{html}
-        </ul>
-      EOHTML
-    end
-
-  end
-end
diff --git a/spec/aggregator_throws_spec.rb b/spec/aggregator_throws_spec.rb
index 41988c96..e5749a96 100644
--- a/spec/aggregator_throws_spec.rb
+++ b/spec/aggregator_throws_spec.rb
@@ -21,15 +21,15 @@ describe JsDuck::Aggregator do
     end
 
     it "detects one throws tag" do
-      @doc[:meta][:throws].length.should == 1
+      @doc[:throws].length.should == 1
     end
 
     it "detects type of exception" do
-      @doc[:meta][:throws][0][:type].should == "Error"
+      @doc[:throws][0][:type].should == "Error"
     end
 
     it "detects description" do
-      @doc[:meta][:throws][0][:doc].should == "Some text\non multiple lines."
+      @doc[:throws][0][:doc].should == "Some text\non multiple lines."
     end
   end
 
@@ -44,11 +44,11 @@ describe JsDuck::Aggregator do
     end
 
     it "detects type as Object" do
-      @doc[:meta][:throws][0][:type].should == "Object"
+      @doc[:throws][0][:type].should == "Object"
     end
 
     it "detects description" do
-      @doc[:meta][:throws][0][:doc].should == "Some description"
+      @doc[:throws][0][:doc].should == "Some description"
     end
   end
 
@@ -64,7 +64,7 @@ describe JsDuck::Aggregator do
     end
 
     it "detects two throws tags" do
-      @doc[:meta][:throws].length.should == 2
+      @doc[:throws].length.should == 2
     end
   end
 
-- 
GitLab