Added :js:class: which makes JS documentation a lot more readible

doc/domains.rst

@@ -557,8 +557,8 @@ The JavaScript domain (name **js**) provides the following directives:
 
 .. rst:directive:: .. js:function:: name(signature)
 
-   Describes a JavaScript function, method or constructor.  If you want to
-   describe arguments as optional use square brackets as :ref:`documented
+   Describes a JavaScript function or method.  If you want to 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
@@ -587,6 +587,23 @@ The JavaScript domain (name **js**) provides the following directives:
         :throws SomeError: For whatever reason in that case.
         :returns: Something
 
+.. rst:directive:: .. js:class:: name
+
+   Describes a constructor that creates an object.  This is basically like
+   a function but will show up with a `class` prefix::
+
+      .. js:class:: MyAnimal(name[, age])
+
+         :param string name: The name of the animal
+         :param number age: an optional age for the animal
+
+   This is rendered as:
+
+      .. js:class:: MyAnimal(name[, age])
+
+         :param string name: The name of the animal
+         :param number age: an optional age for the animal
+
 .. rst:directive:: .. js:data:: name
 
    Describes a global variable or constant.

sphinx/domains/javascript.py

@@ -27,6 +27,9 @@ class JSObject(ObjectDescription):
     #: added
     has_arguments = False
 
+    #: what is displayed right before the documentation entry
+    display_prefix = None
+
     def handle_signature(self, sig, signode):
         sig = sig.strip()
         if '(' in sig and sig[-1:] == ')':
@@ -58,6 +61,9 @@ class JSObject(ObjectDescription):
         signode['object'] = objectname
         signode['fullname'] = fullname
 
+        if self.display_prefix:
+            signode += addnodes.desc_annotation(self.display_prefix,
+                                                self.display_prefix)
         if nameprefix:
             signode += addnodes.desc_addname(nameprefix + '.', nameprefix + '.')
         signode += addnodes.desc_name(name, name)
@@ -116,6 +122,8 @@ class JSObject(ObjectDescription):
             if not obj:
                 return _('%s() (built-in function)') % name
             return _('%s() (%s method)') % (name, obj)
+        elif self.objtype == 'class':
+            return _('%s() (class)') % name
         elif self.objtype == 'data':
             return _('%s (global variable or constant)') % name
         elif self.objtype == 'attribute':
@@ -139,6 +147,11 @@ class JSCallable(JSObject):
     ]
 
 
+class JSConstructor(JSCallable):
+    """Like a callable but with a different prefix"""
+    display_prefix = 'class '
+
+
 class JSXRefRole(XRefRole):
     def process_link(self, env, refnode, has_explicit_title, title, target):
         # basically what sphinx.domains.python.PyXRefRole does
@@ -164,18 +177,21 @@ class JavaScriptDomain(Domain):
     # if you add a new object type make sure to edit JSObject.get_index_string
     object_types = {
         'function':  ObjType(l_('function'),  'func'),
+        'class':     ObjType(l_('class'),     'class'),
         'data':      ObjType(l_('data'),      'data'),
         'attribute': ObjType(l_('attribute'), 'attr'),
     }
     directives = {
         'function':  JSCallable,
+        'class':     JSConstructor,
         'data':      JSObject,
         'attribute': JSObject,
     }
     roles = {
-        'func': JSXRefRole(fix_parens=True),
-        'data': JSXRefRole(),
-        'attr': JSXRefRole(),
+        'func':  JSXRefRole(fix_parens=True),
+        'class': JSXRefRole(fix_parens=True),
+        'data':  JSXRefRole(),
+        'attr':  JSXRefRole(),
     }
     initial_data = {
         'objects': {}, # fullname -> docname, objtype