Minor changes to improve Custom Managers Examples
|Reported by:||valerio.maggio||Owned by:||nobody|
|Has patch:||no||Needs documentation:||no|
|Needs tests:||no||Patch needs improvement:||no|
I've got a couple of suggestions to improve the documentation of Custom Managers https://docs.djangoproject.com/en/1.5/topics/db/managers/.
The first change I would make concerns the code excerpt reported on top of the page (the one containing PollManager, OpinionPoll and Response model classes).
I suggest to remove the "Response" class from the example since it is not referred in the description of the custom manager and it contains a ForeignKey field related to a "Poll" class which is not mentioned in the code snippet.
Imho this class is fairly useless and does not aid the comprehension of the example in any way.
Finally, the second proposed improvements is a "clarification change".
The very first sentence of the paragraph reported in https://docs.djangoproject.com/en/1.5/topics/db/managers/#managers-for-related-objects tells:
"By default, Django uses an instance of a “plain” manager class when accessing related objects (i.e. choice.poll) (...)".
However, "choice.poll" is not a *correct* related object reference as far as I could understand.
I suppose that the referred model classes are those defined in the Tutorial Examples.
However, in the tutorial examples, the related_name in the Poll class has been never defined.
Conversely, to the best of my knowledge, all the examples refer to related objects by using the default related name (i.e., choice.poll_set).
Therefore, a user coming from the tutorial pages could find that example misleading.
I would suggest to change the above example in brackets with "choice.poll_set" in order to make all the references consistent.
Thanks in advance for your consideration.