Opened 5 years ago

Closed 4 years ago

#15558 closed (fixed)

QuerySet reference enhancement + reST cleanup

Reported by: gabrielhurley Owned by: gabrielhurley
Component: Documentation Version: 1.2
Severity: Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

The reST issues aren't really the subject of this ticket (normally I'd just commit those).

However, also in this patch is a chunk that fleshes out the QuerySet class definition. In particular it adds:

  1. The query and using kwargs to the signature.
  2. The ordered and db properties (which are marked as "public" in the source, and are mentioned in the docs elsewhere).

While using should certainly be documented as a kwarg, sql.Query isn't a public API so I'm not sure if documenting query is appropriate.

However, the docs say "here's the formal declaration of a QuerySet" so I'm inclined to say that the declaration should be complete.

I just wanted to get a quick nod from someone else on this one.

Attachments (1)

15558_queryset.diff (6.2 KB) - added by gabrielhurley 5 years ago.

Download all attachments as: .zip

Change History (3)

Changed 5 years ago by gabrielhurley

comment:1 Changed 5 years ago by russellm

  • Triage Stage changed from Unreviewed to Accepted

sql.Query isn't public API, but the existence of the argument isn't a secret. I'm happy for it to be documented with a Jedi-mind trick: "This argument exists so that specialist query subclasses (such as GeoDjango) can reconstruct internal query state. The value itself is an opaque representation of query state. If you need to ask, you don't need to use it".

Otherwise, I'm happy with the patch as provided.

comment:2 Changed 4 years ago by gabrielhurley

  • Resolution set to fixed
  • Status changed from new to closed

In [15776]:

Fixed #15558 -- Improved QuerySet reference docs and cleaned up numerous reST/sphinx problems.

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