[FIX] doc: workarounds for weirdo code & refs

Make UnknownNS more capable (of giving no fucks) so the documentation
builder blows up less on weird-ass code at module toplevels.

UnknownNS should probably be split out from NSDoc though, that requires
odd workarounds in `__getitem__`.

1 files changed, 16 insertions, 1 deletions

diff --git a/doc/_extensions/autojsdoc/parser/jsdoc.py b/doc/_extensions/autojsdoc/parser/jsdoc.py
index e6bd609f298..9e9b0ba441d 100644
--- a/doc/_extensions/autojsdoc/parser/jsdoc.py
+++ b/doc/_extensions/autojsdoc/parser/jsdoc.py
@@ -275,11 +275,26 @@ class ClassDoc(NSDoc):
         d['mixins'] = self.mixins
         return d
 
+DEFAULT = object()
 class UnknownNS(NSDoc):
+    params = () # TODO: log warning when (somehow) trying to access / document an unknown object as ctor?
     def get_property(self, name):
         return super(UnknownNS, self).get_property(name) or \
            UnknownNS({'name': '{}.{}'.format(self.name, name)})
 
+    def __getitem__(self, item):
+        if self._probably_not_property(item):
+            return super().__getitem__(item)
+        return self.get_property(item)
+
+    def _probably_not_property(self, item):
+        return (
+            not isinstance(item, str)
+            or item in (self.namekey, 'name', 'params')
+            or item.startswith(('_', 'guessed_'))
+            or item in self.parsed
+        )
+
 class Unknown(CommentDoc):
     @classmethod
     def from_(cls, source):
@@ -325,7 +340,7 @@ def parse_comments(comments, doctype=None):
     # in case a specific doctype is given, allow overriding it anyway
     return guess(parsed, default=doctype)
 
-def guess(parsed, default=NSDoc):
+def guess(parsed, default=UnknownNS):
     if 'class' in parsed:
         return ClassDoc(parsed)
     if 'function' in parsed: