#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 , 11 years ago
| Triage Stage: | Unreviewed → Accepted |
|---|
comment:2 by , 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 , 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 , 11 years ago
| Has patch: | set |
|---|
comment:5 by , 11 years ago
| Resolution: | → fixed |
|---|---|
| Status: | new → closed |
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.