Signal documentation should mention 'weak' parameter for connect

[Mike_A]

In the documentation for signals: ​http://docs.djangoproject.com/en/dev/topics/signals/

No reference at all is made to the 'weak' parameter of connect.
This caused me to spend about an hour scratching my head as to why my signals didn't seem to work at all.
In the end I realised I needed to set this to False to stop the signal from dropping the callback and silently failing, but only after writing a debugging signal class.

[Sayane]

AND dispatch_uid argument
AND send_robust function
AND disconnect function
;-)

[Aymeric Augustin]

There is already a short explanation for 'weak' here: ​http://docs.djangoproject.com/en/dev/ref/signals/#module-django.db.models.signals

If it should be set to False only for local functions, this explanation is sufficient.

---

On the other hand, the docs do not mention dispatch_uid at all. There is a note in the wiki, which could (should?) be moved to the signal documentation: ​http://code.djangoproject.com/wiki/Signals#Helppost_saveseemstobeemittedtwiceforeachsave

I found #3951 and that wiki page after a long pdb session, trying to understand why my handlers were called twice...

---

send_robust and disconnect only have docstrings, as far as I can tell. So currently it's RTFS :)

[Brian Neal]

I have worked up my first substantial patch for Django for this ticket. Be advised this was the first time I had used sphinx or made a documentation change. I'm hoping a committer can either give me feedback on the patch, or just use it as the basis to provide better words. :-)

I have attempted to document the weak and dispatch_uid arguments to Signal.connect().
I have also attempted to document Signal.send_robust() and Signal.disconnect().

I also fixed some typos in the docstrings of dispatch.py.

[Andy Terra]

+1 on documenting dispatch_uid!

I'm willing to go as far as suggesting that dispatch_uid be made a required kwarg in order to prevent post_save signals being duplicated. It caused me over 24 hours of frustrating commits, rollbacks, and debugging...

[Brian Neal]

airstrike (or anyone else), I need someone to peer review my patch. If you are good with it, please mark this ticket's triage stage to "ready for checkin". Otherwise please leave comments on how I may improve it here. Thanks.

[Gabriel Hurley]

(In [14337]) Fixed #11441 -- Improved signal topic guide, particularly regarding the weak and dispatch_uid parameters to the Signal.connect method. Thanks to Mike_A and sayane for the report, and gremmie for the draft patch.

[Gabriel Hurley]

(In [14338]) [1.2.X] Fixed #11441 -- Improved signal topic guide, particularly regarding the weak and dispatch_uid parameters to the Signal.connect method. Thanks to Mike_A and sayane for the report, and gremmie for the draft patch.

Backport of [14337] from trunk.