#35758: ForeignKey.on_delete example confusing (missing argument it's meant to
document)
-------------------------------------+-------------------------------------
Reporter: kay | Type:
| Cleanup/optimization
Status: new | Component:
| Documentation
Version: 5.1 | Severity: Normal
Keywords: ForeignKey, code | Triage Stage:
examples | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
The code snippet for
[https://docs.djangoproject.com/en/5.1/ref/models/fields/#django.db.models.ForeignKey.on_delete
`ForeignKey.on_delete`] in the docs does not spell out `on_delete`, which
looks odd and can be confusing.
While further up,
[https://docs.djangoproject.com/en/5.1/ref/models/fields/#django.db.models.ForeignKey
at the start] of the `ForeignKey` section, it is explained to be a
positional argument, the subsection documenting the argument itself
doesn't seem like the best place to demonstrate that it isn't actually a
keyword argument. I'd therefore suggest to add it in.
For variety/to remind users of its positional nature, it could instead be
removed from any of the preceding code blocks, which all include it. The
[https://docs.djangoproject.com/en/5.1/ref/models/fields/#id3
`products/models.py` example] might make sense as it's only the second
example in the overall `ForeignKey` section but identical to the first
example.
Relatedly, the intro to the
[https://docs.djangoproject.com/en/5.1/ref/models/fields/#arguments
Arguments] section, which leads into `on_delete`, is ambiguously worded.
It says, "`ForeignKey` accepts **other** arguments that define the details
of how the relation works." (emphasis mine), suggesting what's next are
optional arguments or ones not yet discussed... when `on_delete` is
neither.
--
Ticket URL: <https://code.djangoproject.com/ticket/35758>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/01070191e8c3a555-45e05dde-4859-49ac-b1a5-0075da1a9d70-000000%40eu-central-1.amazonses.com.
