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