Opened 3 years ago

Closed 3 years ago

#19979 closed Cleanup/optimization

Minor changes to improve Custom Managers Examples

Reported by: valerio.maggio Owned by: nobody
Component: Documentation Version: 1.5
Severity: Normal Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no


Dear guys,

I've got a couple of suggestions to improve the documentation of Custom 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 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.


Change History (1)

comment:1 Changed 3 years ago by timo

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Status changed from new to closed

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.
  1. Choice has a ForeignKey to Poll and the related object is accessible by choice.poll.
Note: See TracTickets for help on using tickets.
Back to Top