Opened 9 years ago

Closed 3 years ago

#25444 closed Cleanup/optimization (invalid)

Restructure expressions documentation to better highlight ORM support

Reported by: Josh Smeaton Owned by: nobody
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

The docs in docs/ref/models/expressions.txt could probably do with an overhaul. The original document was very specific about highlighting the use-cases of F expressions in terms of filter and update.

I think the docs should be structured in terms of which queryset methods support expressions. We can then leave the specific expression reference below.

Some of the F() examples can be pulled out into the queryset method sections, but the F() section can still highlight the things it is particularly good at -- like avoiding race conditions.

The docs would be structured like:

=================
Query Expressions
=================

Intro..

Supported QuerySet Operations
=========================

Not every :doc:`QuerySet </ref/models/queryset>` method has full support for
Query Expressions, but the support is growing with each release. Below is a
quick overview showing which methods do have support.

create() and update()
----------------------------------

Intro

Examples

filter() and exclude()
--------------------------------

Intro

Examples

Change History (2)

comment:1 by Tim Graham, 9 years ago

Component: UncategorizedDocumentation
Needs documentation: unset
Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

comment:2 by Mariusz Felisiak, 3 years ago

Resolution: invalid
Status: newclosed
Triage Stage: AcceptedUnreviewed

The current version of expressions reference contains reference material for many expressions and it seems to follow the principles outlined in the ​Diátaxis framework. Closing as "invalid".

Other improvements related with expressions docs are tracked in #25703.

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