Opened 14 years ago

Closed 14 years ago

#15558 closed (fixed)

QuerySet reference enhancement + reST cleanup

Reported by: Gabriel Hurley Owned by: Gabriel Hurley
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: no UI/UX: no

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 Gabriel Hurley 14 years ago.

Download all attachments as: .zip

Change History (3)

by Gabriel Hurley, 14 years ago

Attachment: 15558_queryset.diff added

comment:1 by Russell Keith-Magee, 14 years ago

Triage Stage: UnreviewedAccepted

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 by Gabriel Hurley, 14 years ago

Resolution: fixed
Status: newclosed

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