#22019 closed Cleanup/optimization (fixed)

add section for definitive Model.objects documentation

Reported by: cjerdonek 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 13 months ago by cjerdonek

  • Cc chris.jerdonek@… added
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Summary changed from add section for definitive Models.objects documentation to add section for definitive Model.objects documentation

comment:2 Changed 13 months ago by mjtamlyn

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 13 months ago by cjerdonek

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 13 months ago by timo

  • Easy pickings set
  • Triage Stage changed from Unreviewed to Accepted

comment:5 Changed 12 months ago by nheyning

  • Owner changed from nobody to nheyning
  • Status changed from new to 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 Changed 12 months 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 12 months ago by nheyning

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

comment:8 Changed 12 months ago by erikr

  • Cc eromijn@… added
  • Has patch set
  • Keywords nlsprint14 added; objects removed
  • Resolution fixed deleted
  • Status changed from closed to new
  • Triage Stage changed from Accepted to Ready for checkin

Patch looks fine to me :)

comment:9 Changed 12 months ago by Daniele Procida <daniele@…>

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

In 4f7b7ef6837ee8e385785b164534fd5bc6c38e9f:

Merge pull request #2363 from nheyning/22019_add_objects_doc

Fixed #22019 -- added documentation on Model attributes

comment:10 Changed 12 months ago by cjerdonek

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 12 months ago by EvilDMP

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 12 months ago by cjerdonek

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 12 months ago by cjerdonek

  • Resolution fixed deleted
  • Status changed from closed to new
  • Triage Stage changed from Ready for checkin to Accepted

comment:14 Changed 12 months ago by timo

  • Has patch unset

comment:15 Changed 10 months ago by gtvblame

  • Owner changed from nheyning to anonymous
  • Status changed from new to assigned

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

comment:16 Changed 10 months ago by Tim Graham <timograham@…>

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

In 5b185ecc68c04c0ee63cf44de43d831623daa263:

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

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