Documentation of "for internal use only" code

[Daniele Procida]

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.

[Tim Graham]

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 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.

[Daniele Procida]

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?

[Tim Graham]

Sure, better to remove it sooner than later.

[Tim Graham]

​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.

[Tim Graham]

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.