[Django] #22663: Documentation of "for internal use only" code
Django
-----------------------------------------+------------------------
Reporter: EvilDMP | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-----------------------------------------+------------------------
There is documentation in 1.6 and in dev for code that is not really
intended for public consumption, even though some of it is reasonably
well-known and used.
Documentation in 1.6:
*
https://docs.djangoproject.com/en/1.6/ref/utils/#django.utils.functional.cached_property
*
https://docs.djangoproject.com/en/1.6/ref/utils/#django.utils.functional.allow_lazy
Documentation which will be there in the 1.7 release unless removed:
* https://docs.djangoproject.com/en/1.7/topics/performance/#cached-
property
* https://docs.djangoproject.com/en/1.7/topics/performance/#laziness-in-
django
https://code.djangoproject.com/ticket/21139 has a draft patch that has
remained unmerged because of doubts about the advisibility of documenting
code in `django.utils.functional` that works, but isn't intended for
public use.
This patch extends the documentation, but also adds a warning about using
it: https://github.com/django/django/pull/1777/files#diff-
fae9599a3895c42eca4588a393b61952R426
We have various options including:
* strip all references to it from the documentation on the basis that it
should not be documented
* continue documenting it, but make sure the warnings are clear, and
commit to making the code more suitable for general use
I much prefer the latter option, and dislike the idea of using the absence
of documentation as a strategy.
However, if these references really should not make it into 1.7 then they
should be removed.
--
Ticket URL: <https://code.djangoproject.com/ticket/22663>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: EvilDMP | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by timo):
I don't have an opinion on the functions in question, but just wanted to
chime in on the purpose of Django's documentation according to... itself.
From [https://docs.djangoproject.com/en/dev/misc/api-stability/ API
Stability]: "All the public APIs (everything in this documentation) will
not be moved or renamed without providing backwards-compatible aliases."
I think you would agree that not everything in `django.utils` should be
documented. Is your main concern that some functions in a given file are
documented, but not others? I think we should be free to add things in
`django.utils` where they make sense without worrying about them being
robust, stable APIs. Keep the main thing (a web development framework),
the main thing.
--
Ticket URL: <https://code.djangoproject.com/ticket/22663#comment:1>
Django
Reporter: EvilDMP | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by EvilDMP):
One issue we have is: if some of the things that should not be document
are documented, what should we do about the existing documentation, in 1.6
and 1.7? Should it be removed?
--
Ticket URL: <https://code.djangoproject.com/ticket/22663#comment:2>
Django
Reporter: EvilDMP | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by timo):
Sure, better to remove it sooner than later.
--
Ticket URL: <https://code.djangoproject.com/ticket/22663#comment:3>
Django
Reporter: EvilDMP | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by timo):
[https://github.com/django/django/pull/2707#issuecomment-44414302 from
Simon]:
IMO I don't think we should document all objects present in the
django.utils.functionnal but cached_property is definitely a good
candidate for being part of the public API.
It's a common optimization pattern that newcomers might find hard to
implement correctly. Plus it don't think it would be a great burden to
maintain.
--
Ticket URL: <https://code.djangoproject.com/ticket/22663#comment:4>
Django
Reporter: EvilDMP | Owner: nobody
Type: Uncategorized | Status: closed
Component: Documentation | Version: master
Severity: Normal | Resolution: wontfix
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by timo):
* status: new => closed
* resolution: => wontfix
Comment:
`allow_lazy()` has been documented since 1.4 [62bb4b8c] and I think
`cached_property()` is fine to keep. It's gotten multiple +1s on
[https://github.com/django/django/pull/2707 this PR].
--
Ticket URL: <https://code.djangoproject.com/ticket/22663#comment:5>