Opened 11 years ago

Closed 11 years ago

Last modified 11 years 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 by Russell Keith-Magee, 11 years ago

Triage Stage: UnreviewedAccepted

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 by Tim Graham, 11 years ago

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 by chrismedrela, 11 years ago

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 by chrismedrela, 11 years ago

Has patch: set

comment:5 by Christopher Medrela <chris.medrela@…>, 11 years ago

Resolution: fixed
Status: newclosed

In ac223ff6d1efda56ab1d2e5afe250f744a0a4e64:

Fixed #20735 -- clarified ManyToManyField constructor doc

comment:6 by Tim Graham <timograham@…>, 11 years ago

In d1d09fecf87e9139c9493218c9211e6c91f791a3:

Merge pull request #1350 from chrismedrela/ticket20735

Fixed #20735 -- clarified ManyToManyField constructor doc

comment:7 by Tim Graham <timograham@…>, 11 years ago

In 80a7dd6f7fa0b2fe56978eafdf4a1c7eaf0ad29b:

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

Backport of ac223ff6d1 from master

comment:8 by Tim Graham <timograham@…>, 11 years ago

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