id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
19979	Minor changes to improve Custom Managers Examples	valerio.maggio	nobody	"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

"	Cleanup/optimization	closed	Documentation	1.5	Normal				Unreviewed	0	0	0	0	0	0