Added `doc_field_types` to :class:`JSCallable`, arguments, errors and the return value of JavaScript functions/methods/constructors can now be documented using fields.

3 files changed, 46 insertions, 3 deletions

diff --git a/doc/domains.rst b/doc/domains.rst
index b58e68e1..f48c9516 100644
--- a/doc/domains.rst
+++ b/doc/domains.rst
@@ -554,9 +554,35 @@ The JavaScript domain (name **js**) provides the following directives:
 .. directive:: .. js:function:: name(signature)
 
    Describes a JavaScript function, method or constructor. If you want to
-   document optional arguments use square brackets as
+   describe arguments as optional use square brackets as
    :ref:`documented <signatures>` for Python signatures.
 
+   You can use fields to give more details about arguments and their expected
+   types, errors which may be thrown by the function, and the value being
+   returned::
+
+        .. js:function:: $.getJSON(href, callback[, errback])
+
+           :param string href: An URI to the location of the resource.
+           :param callback: Get's called with the object.
+           :param errback:
+                Get's called in case the request fails. And a lot of other
+                text so we need multiple lines
+           :throws SomeError: For whatever reason in that case.
+           :returns: Something
+
+   This is rendered as:
+
+         .. js:function:: $.getJSON(href, callback[, errback])
+
+           :param string href: An URI to the location of the resource.
+           :param callback: Get's called with the object.
+           :param errback:
+                 Get's called in case the request fails. And a lot of other
+                 text so we need multiple lines.
+           :throws SomeError: For whatever reason in that case.
+           :returns: Something
+
 .. directive:: .. js:data:: name
 
    Describes a global variable or constant.
diff --git a/sphinx/domains/javascript.py b/sphinx/domains/javascript.py
index d9312eee..9698c3d0 100644
--- a/sphinx/domains/javascript.py
+++ b/sphinx/domains/javascript.py
@@ -17,6 +17,7 @@ from sphinx.directives import ObjectDescription
 from sphinx.domains.python import py_paramlist_re as js_paramlist_re
 from sphinx.roles import XRefRole
 from sphinx.util.nodes import make_refnode
+from sphinx.util.docfields import Field, GroupedField, TypedField
 
 js_sig_re = re.compile(
     r'''([^ .]+\.)? # object name
@@ -122,6 +123,17 @@ class JSCallable(JSObject):
     """Description of a JavaScript function, method or constructor."""
     has_arguments = True
 
+    doc_field_types = [
+        TypedField("arguments", label=l_('Arguments'),
+                   names=('argument', 'arg', 'parameter', 'param'),
+                   typerolename='func', typenames=('paramtype', 'type')),
+        GroupedField('errors', label=l_('Throws'), rolename='err',
+                     names=('throws', ),
+                     can_collapse=True),
+        Field('returnvalue', label=l_('Returns'), has_arg=False,
+              names=('returns', 'return')),
+    ]
+
 class JSXRefRole(XRefRole):
     def process_link(self, env, refnode, has_explicit_title, title, target):
         # basically what sphinx.domains.python.PyXRefRole does
@@ -143,6 +155,7 @@ class JavaScriptDomain(Domain):
     """JavaScript language domain."""
     name = 'js'
     label= 'JavaScript'
+    # if you add a new object type make sure to edit JSObject.get_index_string
     object_types = {
         'function'  : ObjType(l_('js function'), 'func'),
         'data'      : ObjType(l_('js data'), 'data'),
diff --git a/tests/root/objects.txt b/tests/root/objects.txt
index 60bb120d..6b392f36 100644
--- a/tests/root/objects.txt
+++ b/tests/root/objects.txt
@@ -81,10 +81,14 @@ Javascript items
 .. js:data:: bar
 
 .. documenting the method of any object
-.. js:function:: bar.baz()
+.. js:function:: bar.baz(href, callback[, errback])
 
-.. js:attribute:: bar.spam
+   :param string href: The location of the resource.
+   :param callback: Get's called with the data returned by the resource.
+   :throws InvalidHref: If the `href` is invalid.
+   :returns: `undefined`
 
+.. js:attribute:: bar.spam
 
 References
 ==========