Bug: Thunderbird docs fail to build (jsdoc) due to error in NotificationManager.sys.mjs
Status: RESOLVED
Priority: --
Resolution: FIXED
Created: 2024-09-23 17:53:45+00:00
Resolved: 2024-09-24 17:01:15+00:00

Running mach tb-doc fails currently due to a problem in NotificationManager.sys.mjs. Specifically its:
https://searchfox.org/comm-central/rev/59025cb512ac088aa25e278e660ff65269e74dde/mail/components/inappnotifications/modules/NotificationManager.sys.mjs#54-56

```javascript
  /**
   * Check if a notification has UI that should be shown. The only notification
   * type that doesn't have UI is the "donations_old" type, which imitates the
   * appeal behavior, where we open a webseite in the user's browser.
   *
   * @param {object} notification
   * @returns {boolean} If this notification should show a popup in the UI.
   */
  static #isNotificationWithUI(notification) {
    return notification.type !== "donations_old";
  }
```

Sphinx throws this error:
```
./mail/components/inappnotifications/modules/NotificationManager.sys.NotificationManager
./mail/components/inappnotifications/modules/NotificationManager.sys.NotificationManager#MAX_MS_BETWEEN_NOTIFICATIONS
./mail/components/inappnotifications/modules/NotificationManager.sys.NotificationManager.

Traceback (most recent call last):
  File "/home/rob/.mozbuild/srcdirs/m-c-068a5b9ccbc1/_virtualenvs/tb_docs/lib/python3.12/site-packages/sphinx/events.py", line 97, in emit
    results.append(listener.handler(self.app, *args))
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/rob/.mozbuild/srcdirs/m-c-068a5b9ccbc1/_virtualenvs/tb_docs/lib/python3.12/site-packages/sphinx_js/__init__.py", line 159, in analyze
    app._sphinxjs_analyzer = analyzer.from_disk(abs_source_paths,
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/rob/.mozbuild/srcdirs/m-c-068a5b9ccbc1/_virtualenvs/tb_docs/lib/python3.12/site-packages/sphinx_js/jsdoc.py", line 76, in from_disk
    return cls(json, base_dir)
           ^^^^^^^^^^^^^^^^^^^
  File "/home/rob/.mozbuild/srcdirs/m-c-068a5b9ccbc1/_virtualenvs/tb_docs/lib/python3.12/site-packages/sphinx_js/jsdoc.py", line 48, in __init__
    self._doclets_by_path.add_many((full_path_segments(d, base_dir), d)
  File "/home/rob/.mozbuild/srcdirs/m-c-068a5b9ccbc1/_virtualenvs/tb_docs/lib/python3.12/site-packages/sphinx_js/suffix_tree.py", line 44, in add_many
    for segs, value in segments_and_values:
                       ^^^^^^^^^^^^^^^^^^^
  File "/home/rob/.mozbuild/srcdirs/m-c-068a5b9ccbc1/_virtualenvs/tb_docs/lib/python3.12/site-packages/sphinx_js/jsdoc.py", line 48, in <genexpr>
    self._doclets_by_path.add_many((full_path_segments(d, base_dir), d)
                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/rob/.mozbuild/srcdirs/m-c-068a5b9ccbc1/_virtualenvs/tb_docs/lib/python3.12/site-packages/sphinx_js/jsdoc.py", line 185, in full_path_segments
    path_and_formal_params['path'].parse(path))
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/rob/.mozbuild/srcdirs/m-c-068a5b9ccbc1/_virtualenvs/tb_docs/lib/python3.12/site-packages/parsimonious/expressions.py", line 141, in parse
    node = self.match(text, pos=pos)
           ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/rob/.mozbuild/srcdirs/m-c-068a5b9ccbc1/_virtualenvs/tb_docs/lib/python3.12/site-packages/parsimonious/expressions.py", line 158, in match
    raise error
parsimonious.exceptions.ParseError: Rule 'name' didn't match at '' (line 1, column 90).
```

I don't quite understand what specifically it's complaining about, however I can tell you:
- I tracked this down by hacking jsdoc to print the "path" in `full_path_segments` right before calling `path_and_formal_params['path'].parse(path))`. That's where the first three lines of this log are coming from.
- It looks like it's having problems with the private function name perhaps? But then, it had no issue with `InAppNotificationManager.#showNotification` ... 
- Maybe it's having trouble with `notification.type` not being found?
- Either way, comment out that function and docs build