Terminology for third-party modules is confusing

[babolivier]

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.

[richvdh]

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]

(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.)

I've had this objection to the term "module" since day one.

[babolivier]

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)?

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 ModuleApi class, etc).

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?

#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.

(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.)

Yeah I wholly agree with you on this.

[richvdh]

#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.

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]

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).

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.

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.

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".