Opened 2 years ago

Closed 2 years ago

Last modified 2 years ago

#19712 closed Cleanup/optimization (fixed)

admindocs Model reference is incomplete and wrongly described

Reported by: EvilDMP Owned by: nobody
Component: Documentation Version: 1.4
Severity: Normal Keywords:
Cc: timograham@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

https://docs.djangoproject.com/en/dev/ref/contrib/admin/admindocs/#model-reference

The models section of the admindocs page describes each model in the system along 
with all the fields and methods available on it

That's only true of methods that are not properties, and don't have multiple arguments.

I can see why the latter methods are not included (they won't always be available in templates), but I can see no reason why properties should be excluded.

Finally, the admindocs say: "Fields on <whatever> objects" - wouldn't "attributes" be more accurate?

Attachments (1)

19712.diff (930 bytes) - added by timo 2 years ago.

Download all attachments as: .zip

Change History (7)

comment:1 Changed 2 years ago by timo

  • Component changed from Uncategorized to Documentation
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted
  • Type changed from Uncategorized to Cleanup/optimization

Changed 2 years ago by timo

comment:2 Changed 2 years ago by timo

  • Cc timograham@… added
  • Has patch set

Added patch for the first clarification. Not sure what the "Finally" issue is referring to?

comment:3 Changed 2 years ago by EvilDMP

Say you visit /admin/doc/models/auth.user/.

It will say there: <h1>Fields on User objects</h1>.

However, it doesn't just list fields, it lists all kinds of attributes of User, including:

  • methods
  • model fields
  • some methods on relations, such as count() and all()

but not:

  • methods decorated with @property
  • methods beginning with _
  • particular methods including get_absolute_url()

So it's just a bit misleading, that's all.

comment:4 Changed 2 years ago by Tim Graham <timograham@…>

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

In b5b63079bd758c4492ab6b6935edec3346016f25:

Fixed #19712 - Clarified admindocs regarding which attributes appear.

Thanks Daniele Procida for the report.

comment:5 Changed 2 years ago by Tim Graham <timograham@…>

In a9048c40edffd189e9b99699c5947e69f9ca15f1:

[1.5.x] Fixed #19712 - Clarified admindocs regarding which attributes appear.

Thanks Daniele Procida for the report.

Backport of b5b63079bd from master

comment:6 Changed 2 years ago by Tim Graham <timograham@…>

In 79715f267c7b301dc246b35182ede3e269a15aa2:

Fixed misleading heading on admindocs models page; refs #19712.

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