Opened 3 years ago

Closed 3 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 about objects 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 Changed 3 years ago by Chris Jerdonek

Cc: chris.jerdonek@… added
Summary: add section for definitive Models.objects documentationadd section for definitive Model.objects documentation

comment:2 Changed 3 years ago by Marc Tamlyn

There is no need for extensive documentation of objects - it's a Manager 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.

comment:3 Changed 3 years ago by Chris Jerdonek

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 Changed 3 years ago by Tim Graham

Easy pickings: set
Triage Stage: UnreviewedAccepted

comment:5 Changed 3 years ago by nheyning

Owner: changed from nobody to nheyning
Status: newassigned

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 Changed 3 years ago by nheyning

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 Changed 3 years ago by nheyning

Resolution: fixed
Status: assignedclosed

comment:8 Changed 3 years ago by Erik Romijn

Cc: eromijn@… added
Has patch: set
Keywords: nlsprint14 added; objects removed
Resolution: fixed
Status: closednew
Triage Stage: AcceptedReady for checkin

Patch looks fine to me :)

comment:9 Changed 3 years ago by Daniele Procida <daniele@…>

Resolution: fixed
Status: newclosed

In 4f7b7ef6837ee8e385785b164534fd5bc6c38e9f:

Merge pull request #2363 from nheyning/22019_add_objects_doc

Fixed #22019 -- added documentation on Model attributes

comment:10 Changed 3 years ago by Chris Jerdonek

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 Changed 3 years ago by Daniele Procida

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 Changed 3 years ago by Chris Jerdonek

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 Changed 3 years ago by Chris Jerdonek

Resolution: fixed
Status: closednew
Triage Stage: Ready for checkinAccepted

comment:14 Changed 3 years ago by Tim Graham

Has patch: unset

comment:15 Changed 3 years ago by gtvblame

Owner: changed from nheyning to anonymous
Status: newassigned

Take this ticket to work on during DjangoCon Europe 2014 sprint.

comment:16 Changed 3 years ago by Tim Graham <timograham@…>

Resolution: fixed
Status: assignedclosed

In 5b185ecc68c04c0ee63cf44de43d831623daa263:

Fixed #22019 -- Added Model.objects reference documentation.

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