id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
22663	"Documentation of ""for internal use only"" code"	Daniele Procida	nobody	"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."	Uncategorized	closed	Documentation	dev	Normal	wontfix			Unreviewed	0	0	0	0	0	0