[Django] #34352: Clarify Signals documentation
Django
------------------------------------------------+------------------------
Reporter: PASCAL FOUQUE | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 4.1
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
------------------------------------------------+------------------------
Currently, the "Signals" documentation presents some inconsistency, mostly
due to naming.
- Different terms are used: "Signal handler", "Signal Receiver",
"callback"
- Users are told to store "Signal handlers/Receivers" into a module called
"signals", which connects to a Signal from another module called "signal".
I think some minor changes, could help understand this feature:
- 1. Remove the term "callback": can lead to confusion with a function
defined per call
- 2. Introducing another module name to define "Signal handlers/Receivers"
would help understand this feature involves two different actors.
- 3. Unify the naming of "Signal handlers" / "Signal Receiver", I'm
wondering if we need to keep both terms, or keep the term "receiver"
reserved for the function and use "Signal Handler" for the connected
function.
NB: I didn't make much research on how this kind of feature is explained
in other frameworks / technologies
--
Ticket URL: <https://code.djangoproject.com/ticket/34352>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
Reporter: PASCAL FOUQUE | Owner: nobody
Cleanup/optimization |
Component: Documentation | Version: 4.1
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Mariusz Felisiak):
> I think some minor changes, could help understand this feature:
> - 1. Remove the term "callback": can lead to confusion with a function
defined per call
"callback" is widely used in Python and Django docs as a function that is
passed to another function as an argument, in this case to
`Signal.connect()`. I don't find it confusing, however, we could rename
`my_callback()` to `my_signal_receiver()` to make it even more clearer.
> - 2. Introducing another module name to define "Signal
handlers/Receivers" would help understand this feature involves two
different actors.
Users can freely organize their code, we recommend keeping signal
receivers in `signals.py`. I'm not sure what other module you're
proposing.
> - 3. Unify the naming of "Signal handlers" / "Signal Receiver"
Agreed we could use the same term.
--
Ticket URL: <https://code.djangoproject.com/ticket/34352#comment:1>
Django
--------------------------------------+------------------------------------
Reporter: PASCAL FOUQUE | Owner: nobody
Component: Documentation | Version: 4.1
Severity: Normal | Resolution:
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Mariusz Felisiak):
* stage: Unreviewed => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/34352#comment:2>