Minor changes to improve Custom Managers Examples

[valerio.maggio]

Dear guys,

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.

Best,
Valerio

[Tim Graham]

Thanks for the feedback, however, it looks to me like the documentation is correct as is.

1. The table for the Response model (polls_response) is used by the custom SQL query a few lines above.

2. Choice has a ForeignKey to Poll and the related object is accessible by choice.poll.