[Django] #35758: ForeignKey.on_delete example confusing (missing argument it's meant to document)

[Django]

#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.

[Django]

#35758: ForeignKey.on_delete example confusing (missing argument it's meant to
document)
-------------------------------------+-------------------------------------

Reporter: kay | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:
Keywords: ForeignKey, code | Triage Stage: Accepted
examples |

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* stage: Unreviewed => Accepted

Comment:

Agreed. Would you like to provide a patch?

I would say this doesn't need a ticket but as you've raised one, accepting
--
Ticket URL: <https://code.djangoproject.com/ticket/35758#comment:1>