Opened 10 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 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 by Chris Jerdonek, 10 years ago

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

comment:2 by Marc Tamlyn, 10 years ago

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 by Chris Jerdonek, 10 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 Tim Graham, 10 years ago

Easy pickings: set
Triage Stage: UnreviewedAccepted

comment:5 by nheyning, 10 years ago

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 by nheyning, 10 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 nheyning, 10 years ago

Resolution: fixed
Status: assignedclosed

comment:8 by Sasha Romijn, 10 years ago

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 by Daniele Procida <daniele@…>, 10 years ago

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 by Chris Jerdonek, 10 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 Daniele Procida, 10 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 Chris Jerdonek, 10 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 Chris Jerdonek, 10 years ago

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

comment:14 by Tim Graham, 10 years ago

Has patch: unset

comment:15 by gtvblame, 10 years ago

Owner: changed from nheyning to anonymous
Status: newassigned

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

comment:16 by Tim Graham <timograham@…>, 10 years ago

Resolution: fixed
Status: assignedclosed

In 5b185ecc68c04c0ee63cf44de43d831623daa263:

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

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