Opened 11 years ago
Closed 10 years ago
#22019 closed Cleanup/optimization (fixed)
add section for definitive Model.objects documentation
Reported by: | Chris Jerdonek | Owned by: | anonymous |
---|---|---|---|
Component: | Documentation | Version: | 1.6 |
Severity: | Normal | Keywords: | models nlsprint14 |
Cc: | chris.jerdonek@…, eromijn@… | Triage Stage: | Accepted |
Has patch: | no | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | yes | UI/UX: | no |
Description
I can't seem to find the model class attribute objects
documented in any of the models reference sections. In addition, there doesn't seem to be an obvious central place where objects
is documented (and in particular, a clear place where the word "objects" can internally link to). I think this place should be somewhere in the reference/API section.
Currently, the most detailed documentation of objects
seems to be here, in the "Retrieving objects" subsection of the "Making queries" section of the introductory "Models and databases" topic section. However, objects
is referred to much earlier than that, for example several times in the previous "Models" section.
My recommendations would be:
- add to the Models reference a definitive section about the
objects
class attribute, and include there a hyperlink to the introductory section aboutobjects
that I mentioned above, - hyperlink the first mentions of
objects
in the models introductory sections to the definitive section, and - in particular, hyperlink the introductory section about
objects
to the definitive section.
Change History (16)
comment:1 by , 11 years ago
Cc: | added |
---|---|
Summary: | add section for definitive Models.objects documentation → add section for definitive Model.objects documentation |
comment:2 by , 11 years ago
comment:3 by , 11 years ago
It doesn't need to be extensive. It might only be a few sentences, say like the Model.save docs, which primarily points the reader to other places.
The point is just to have Model.objects
appear some place in the API docs. It can simply be a hub that links people elsewhere (e.g. the "Retrieving objects" section I mentioned above as well as the managers section you mentioned).
comment:4 by , 11 years ago
Easy pickings: | set |
---|---|
Triage Stage: | Unreviewed → Accepted |
comment:5 by , 11 years ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
I've been discussing this issue with Daniele Procida at the 2014 Amsterdam Django sprint.
My plan is to add a section to Model Topics page called Model attributes. The manager is the first attribute that will discussed here, with objects as its default name
comment:6 by , 11 years ago
Reference documentation is actually missing a section about managers. To fill the gab I added some explanation to the model topic.
Because I focussed more on Model attributes in general, it didn't seem logical any more to make objects in other documentation link to this section.
comment:7 by , 11 years ago
Resolution: | → fixed |
---|---|
Status: | assigned → closed |
Pullrequest: https://github.com/django/django/pull/2363
comment:8 by , 11 years ago
Cc: | added |
---|---|
Has patch: | set |
Keywords: | nlsprint14 added; objects removed |
Resolution: | fixed |
Status: | closed → new |
Triage Stage: | Accepted → Ready for checkin |
Patch looks fine to me :)
comment:9 by , 11 years ago
Resolution: | → fixed |
---|---|
Status: | new → closed |
comment:10 by , 11 years ago
My suggestion was to add objects
to the reference API. It's not intuitive if only the introductory section covers this but not the more detailed reference section. I also suggested hyperlinking some mentions of objects for this issue, for example here.
comment:11 by , 11 years ago
It's somewhat hard to see where in the ref/models documentations this might go.
I don't see that it warrants a section of its own, and yet there's no adequate place for it in the existing sections.
I agree that the concerns raised in the ticket are valid, and also not fully addressed, but I don't think that a very satisfactory answer will be found within given the current structure of the documentation.
Feel free to re-open the ticket though.
comment:12 by , 11 years ago
Reopening to address the two points in my previous comment (hyperlinking and adding to the reference section).
Yes, I agree that with the current section organization of the model reference section, it's not clear where an objects
class attribute should go (all of the sections are titled somewhat specifically).
Looking at the sections more carefully, I think the most natural location is probably the Model instance reference section, even though strictly speaking that section is about instance attributes and methods rather than class attributes. But the introductory sentence does read, "This document describes the details of the Model API." Also, early on in the "Creating objects" subsection, the page does discuss adding a custom objects
manager.
If we want to be more correct with the title, we could even consider changing the title to the more general "Model class reference."
comment:13 by , 11 years ago
Resolution: | fixed |
---|---|
Status: | closed → new |
Triage Stage: | Ready for checkin → Accepted |
comment:14 by , 11 years ago
Has patch: | unset |
---|
comment:15 by , 10 years ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
Take this ticket to work on during DjangoCon Europe 2014 sprint.
comment:16 by , 10 years ago
Resolution: | → fixed |
---|---|
Status: | assigned → closed |
There is no need for extensive documentation of
objects
- it's aManager
instance so the managers doc is the reference: https://docs.djangoproject.com/en/dev/topics/db/managers/Making these links more explicit might be useful though.