Implement @throws as builtin tag.

Author: nene

lib/jsduck/class_formatter.rb

@@ -48,6 +48,7 @@ def format_member(m)
       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

lib/jsduck/doc_parser.rb

@@ -132,6 +132,8 @@ def parse_loop
           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 @@ def at_var
       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.

lib/jsduck/merger.rb

@@ -162,6 +162,7 @@ def create_method(docs, code)
         :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 @@ def detect_return(doc_map, default_type="undefined")
       }
     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)

lib/jsduck/renderer.rb

@@ -318,6 +318,10 @@ def render_params_and_return(item)
         doc << render_return(ret)
       end
 
+      if item[:throws]
+        doc << render_throws(item[:throws])
+      end
+
       doc
     end
 
@@ -351,6 +355,22 @@ def render_return(ret)
         "</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

lib/jsduck/tag/throws.rb

@@ -21,15 +21,15 @@ def parse(string)
     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 @@ def parse(string)
     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 @@ def parse(string)
     end
 
     it "detects two throws tags" do
-      @doc[:meta][:throws].length.should == 2
+      @doc[:throws].length.should == 2
     end
   end