select_related() documentation examples use incorrect fieldnames, and are slightly misleading

[Daniele Procida]

​https://docs.djangoproject.com/en/dev/ref/models/querysets/#django.db.models.query.QuerySet.select_related says that if you have the models

class City(models.Model):
    # ...
    pass

class Person(models.Model):
    # ...
    hometown = models.ForeignKey(City)

class Book(models.Model):
    # ...
    author = models.ForeignKey(Person)

then you can do a Book.objects.select_related('person__city').get(id=4) .

But in fact that, and the other examples that follow, should be using select_related('author__hometown') (the names of the fields, rather than of the models they refer to).

These examples should be changed.

A related issue in the same section: the examples might lead one to believe that select_related works only when retrieving a single item with get() (unlike prefetch_related, whose examples involve retrieving multiple objects), whereas this is not in fact the case.

An example using filter() or some more explicit wording in the description (or both) would help here.

[Tim Graham <timograham@…>]

In e958c760f90672e6d1422fb5509f64c12527a451:

Fixed #23732 -- Corrected and enhanced select_related() docs.

Thanks Daniele Procida for the report and review.

[Tim Graham <timograham@…>]

In e876c7f1ee4e0f071f7920b729829a3373ce2a9b:

[1.7.x] Fixed #23732 -- Corrected and enhanced select_related() docs.

Thanks Daniele Procida for the report and review.

Backport of e958c760f9 from master