1449773 - Specs index should clarify that only exported types need to be listed

Status: NEW

(DevTools :: General, enhancement)

Description

[J. Ryan Stinnett [:jryans] (Use needinfo, replies may be slow)]

We added devtools/shared/specs/index.js to lazy load actor types in bug 1399589.

The "types" that that index wants to include appear to be only actor types (not dict types, etc.), but that is not stated anywhere in the file.

We should clarify what types are meant to be listed here.

Comment 1

[Alexandre Poirot [:ochameau]]

Hum. Actually, we can specify all types declared by each module, including dict types.
But the base requirement is to specify all "exported" types, no matter if it is actor or dict type.
It allows other actor to use another spec's type, otherwise, it won't be able to find/use it.
I expect `reg` to be null here and this method will throw "Unknown type: xxx":
  https://searchfox.org/mozilla-central/source/devtools/shared/protocol.js#73

As dict types are very rarely used by another spec, we rarely specify any in index.js's list.
At least one appear in this list:
  https://searchfox.org/mozilla-central/source/devtools/shared/specs/index.js#124-126

I imagine we could tweak this comment:
  https://searchfox.org/mozilla-central/source/devtools/shared/specs/index.js#9-10
  // All spec and front modules should be listed here
  // in order to be referenced by any other spec or front module.
It is not super detailed, but correct.

But may be we are missing some notes about this index in:
  https://searchfox.org/mozilla-central/source/devtools/docs/backend/protocol.js.md
?

Comment 2

[J. Ryan Stinnett [:jryans] (Use needinfo, replies may be slow)]

Ah okay, I see, thanks!

Yes, I think we add more comments to the index to clarify it's only exported types that matter.  If you add a new spec that doesn't export anything, then you don't need an entry.  Right now, it's a bit unclear I think, especially for non-experts.

Also yes, let's update that p.js doc as well.

Beyond that, we should also extend p.js to have a clear error message when a spec entry was needed but is missing.  Right now, it looks like it will probably just fail with a generic "Unknown type"[1].

[1]: https://searchfox.org/mozilla-central/rev/57bbc1ac58816dc054df242948f3ecf75e12df5f/devtools/shared/protocol.js#104