Opened 11 years ago
Closed 10 years ago
#22663 closed Uncategorized (wontfix)
Documentation of "for internal use only" code
Reported by: | Daniele Procida | Owned by: | nobody |
---|---|---|---|
Component: | Documentation | Version: | dev |
Severity: | Normal | Keywords: | |
Cc: | Triage Stage: | Unreviewed | |
Has patch: | no | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | no | UI/UX: | no |
Description
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.
Change History (5)
comment:1 by , 11 years ago
comment:2 by , 11 years ago
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?
comment:4 by , 10 years ago
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.
comment:5 by , 10 years ago
Resolution: | → wontfix |
---|---|
Status: | new → closed |
allow_lazy()
has been documented since 1.4 [62bb4b8c] and I think cached_property()
is fine to keep. It's gotten multiple +1s on this PR.
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 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 indjango.utils
where they make sense without worrying about them being robust, stable APIs. Keep the main thing (a web development framework), the main thing.