This repository was archived by the owner on Apr 26, 2024. It is now read-only.
Repository navigation
This repository was archived by the owner on Apr 26, 2024. It is now read-only.
Terminology for third-party modules is confusing #12186
Description
Currently we have a module system (or interface) where modules can register callbacks and use module API methods, which are different things. It feels like we keep confusing them, for example calling a module callback a module API (which is even more confusing because it technically is an API but just isn't a method of the ModuleApi class).
We need to figure out a better terminology.
Activity
richvdh commentedon Mar 9, 2022
so to be clear, the problem isn't with the word "module", it's about which direction the call is made (module -> synapse or synapse -> module)?
Intuitively, the difference seems fairly clear to me (synapse exposes an API which modules can use. Modules do not expose an API; rather they register callbacks via the module API). But perhaps I'm missing some subtlety? Do you have specific examples of the confusion?
(I'd argue the word "module" is confusing, given that Python attaches a particular meaning to that word. "Plug-in" might be better. But renaming it now might be harder work than is justified.)
DMRobertson commentedon Mar 9, 2022
I've had this objection to the term "module" since day one.
babolivier commentedon Mar 9, 2022
It's about the words we use to name different parts of Synapse's module system (eg we sometimes refer to Synapse's module "interface" which isn't the same as the module "API", callbacks are technically part of Synapse's overall module API, just not of the
ModuleApiclass, etc).#12028 is the most recent example I've seen (I've renamed it for clarity). In general, I think I've had to correct people at least 50% of the time (probably more) because they're talking about "the module API" to refer to callbacks.
Yeah I wholly agree with you on this.
richvdh commentedon Mar 9, 2022
mmmhmm. I'm not sure that changing our terminology is the right solution to people wanting to use words to mean what they want them to mean, rather than what everyone else expects them to mean (or, indeed, is going to solve that problem at all).
It feels to me like this particular case might be a hangover from when you did actually need to implement a given API in your module - the terminology has stuck, even though that's no longer the case. Again, I don't think that changing how we refer to these things is going to change the fact that people will still use old terminology.
babolivier commentedon Mar 9, 2022
To me it feels like "what everyone expects them to mean" in this case is callbacks being part of the module API (which they aren't in our definition because imo we have a weird definition of what the module API is). I very much feel like we're the ones wanting to use words to mean what we want them to mean rather than what people expect them to mean.
I wouldn't qualify it as legacy terminology (also because we've never used the term "module API" to mean the methods implemented inside a module afaict). To me callbacks that implement the interfaces described in the Synapse documentation are very much part of what I would otherwise call a module API - except for some reason we have decided to only call one bit of that interface "API".