Opened 21 months ago

Closed 21 months ago

Last modified 21 months ago

#20735 closed Cleanup/optimization (fixed)

Confusing ManyToManyField constructor documentation

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

Description

The documentation says (https://docs.djangoproject.com/en/dev/ref/models/fields/#django.db.models.ManyToManyField):

class ManyToManyField(othermodel[, * *options])

A many-to-many relationship. Requires a positional argument: the class to which the model is related. This works exactly the same as it does for ForeignKey, including all the options regarding recursive and lazy relationships.

It's confusing, because to_field option is valid for ForeignKey, but it's not supported by ManyToManyFields.

Change History (8)

comment:1 Changed 21 months ago by russellm

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

I spoke with Chris about this over Skype. To clarify - the confusing part is the wording of "exactly the same... as ForeignKey". Chris took that to mean that ManyToManyField took all the same arguments as ForeignKey, when the statement was only trying to say that the first argument -- the model reference -- is handled the same as in ForeignKey.

comment:2 Changed 21 months ago by timo

How about if we rephrased it like this:

"Requires a positional argument: the class to which the model is related, which works exactly the same as it does for ForeignKey, including all the options regarding recursive and lazy relationships."

comment:3 Changed 21 months ago by chrismedrela

That's much better. Additionally, I would like to remove some words: "including all the options regarding recursive and lazy relationships". One may think about **options keyword arguments when they glance at "including all the options" and don't read to the very end of the statement. I've created a pull request: https://github.com/django/django/pull/1350.

comment:4 Changed 21 months ago by chrismedrela

  • Has patch set

comment:5 Changed 21 months ago by Christopher Medrela <chris.medrela@…>

  • Resolution set to fixed
  • Status changed from new to closed

In ac223ff6d1efda56ab1d2e5afe250f744a0a4e64:

Fixed #20735 -- clarified ManyToManyField constructor doc

comment:6 Changed 21 months ago by Tim Graham <timograham@…>

In d1d09fecf87e9139c9493218c9211e6c91f791a3:

Merge pull request #1350 from chrismedrela/ticket20735

Fixed #20735 -- clarified ManyToManyField constructor doc

comment:7 Changed 21 months ago by Tim Graham <timograham@…>

In 80a7dd6f7fa0b2fe56978eafdf4a1c7eaf0ad29b:

[1.5.x] Fixed #20735 -- clarified ManyToManyField constructor doc

Backport of ac223ff6d1 from master

comment:8 Changed 21 months ago by Tim Graham <timograham@…>

In 9bb04b1a6bcb98e7061f475aaac58add89d048ba:

[1.6.x] Fixed #20735 -- clarified ManyToManyField constructor doc

Backport of ac223ff6d1 from master

Note: See TracTickets for help on using tickets.
Back to Top