[FIX] various broken JS docstrings

Resulting in sphinx warnings or ill-formatted doc all the way to the
doc not building at all.

2 files changed, 12 insertions, 0 deletions

diff --git a/doc/_extensions/autojsdoc/ext/directives.py b/doc/_extensions/autojsdoc/ext/directives.py
index 649de9d151c..c666b07a20d 100644
--- a/doc/_extensions/autojsdoc/ext/directives.py
+++ b/doc/_extensions/autojsdoc/ext/directives.py
@@ -15,6 +15,7 @@ from sphinx.ext.autodoc import members_set_option, bool_option, ALL
 from autojsdoc.ext.extractor import read_js
 from ..parser import jsdoc, types
 
+class DocumenterError(Exception): pass
 
 @contextlib.contextmanager
 def addto(parent, newnode):
@@ -157,6 +158,11 @@ class Documenter(object):
         """
         :rtype: List[nodes.Node]
         """
+        try:
+            return self._generate(all_members=all_members)
+        except Exception as e:
+            raise DocumenterError("Failed to document %s" % self.item) from e
+    def _generate(self, all_members=False):
         objname = self.item.name
         prefixed = (self.item['sourcemodule'].name + '.' + objname) if self.item['sourcemodule'] else None
         objtype = self.objtype
diff --git a/doc/_extensions/autojsdoc/parser/jsdoc.py b/doc/_extensions/autojsdoc/parser/jsdoc.py
index 55ec998c94f..ff6d3196254 100644
--- a/doc/_extensions/autojsdoc/parser/jsdoc.py
+++ b/doc/_extensions/autojsdoc/parser/jsdoc.py
@@ -233,6 +233,12 @@ class ModuleDoc(NSDoc):
         vars['exports'] = self.exports
         return vars
 
+    def __str__(self):
+        s = super().__str__()
+        if self['sourcefile']:
+            s += " in file " + self['sourcefile']
+        return s
+
 class ClassDoc(NSDoc):
     namekey = 'class'
     @property