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
23688	cached_property should preserve docstring of wrapped function	John-Scott Atlakson	nobody	"This was prompted by noticing an issue in the [http://wagtail.readthedocs.org/en/latest/core_components/pages/creating_pages.html#wagtail.wagtailcore.models.Page.specific Wagtail sphinx documentation] where Sphinx pulls the docstring for cached_property rather than the decorated methods (`specific` and `specific_class` in the Wagtail documentation). The [http://sphinx-doc.org/ext/autodoc.html#directive-autoattribute Sphinx documentation] says decorators need to be well-behaved and preserve the docstring so I've submitted a [https://github.com/django/django/pull/3394 pull request] in attempt to make it well-behaved. 

Berker Peksag requested I open a ticket to discuss and to add tests. I'm not sure how to test this since this results in downstream issues when other projects use cached_property AND try to auto-generate documentation using Sphinx. If someone can point me in the right direction I'll be happy to put together a test case, but it's late Sunday evening where I'm at and it's not occurring to me how to sensibly proceed.

FYI, this specific issue has been brought up on the [https://groups.google.com/d/msg/django-developers/MytkDIgZ9kA/1bql07ZgonEJ mailing list] before but there was no direct response on this point."	Cleanup/optimization	closed	Utilities	1.7	Normal	fixed			Accepted	1	0	1	0	1	0