Docs: Badly wrong explanation of View.as_view() and its use in urlconf

[Graham Wideman]

In the Introduction to class-based view (for example, ​https://docs.djangoproject.com/en/1.10/topics/class-based-views/intro/) the explanation for the as_view() method is wrong in a way which undermines clear understanding of a crucial piece of the CBV apparatus.

Existing narrative: "Because Django’s URL resolver expects to send the request and associated arguments to a callable function, not a class, class-based views have an as_view() class method which serves as the callable entry point to your class. The as_view entry point creates an instance of your class and calls its dispatch() method."

The as_view() class method is NOT the entry point and does NOT instantiate your class. If as_view() were the entry point, then its use in urlpatterns would omit the function brackets, and the subsequent Note about setting class attributes would make no sense.

The narrative should be changed to something more like:

"Django’s URL resolver expects to send the request and associated arguments to a callable function (as it does for function-based views), and so will not accept a class as the view argument in the url() function. Consequently, the View base class provides the as_view() class method which *returns a class method* that serves as the callable entry point to your class. Note that the as_view() function itself is *not* the entry point per se. The function that as_view() returns (called later by the URL resolver when a request arrives for a URL matching the associated pattern) is responsible for instantiating your actual view class, and calling its dispatch() method."

[Tim Graham]

Care to submit a pull request?

[Graham Wideman]

Replying to Tim Graham:

Care to submit a pull request?

I am not really in a position any time soon to divert to figuring out what all I'd need to fork to make this change and have it end up as an appropriate patch. Also I wouldn't know how to get this change to apply to all the generations of docs it applies to. So, I'm afraid if you wait for me this probably won't get done. Sorry :-(

[Tim Graham]

Care to review my ​PR?

[Tim Graham <timograham@…>]

In f2ff1b2f:

Fixed #27289 -- Corrected View.as_view() explanation.

Thanks Graham Wideman for the report.

[Tim Graham <timograham@…>]

In 131098b9:

[1.10.x] Fixed #27289 -- Corrected View.as_view() explanation.

Thanks Graham Wideman for the report.

Backport of f2ff1b2fabbe26d5e61d690c4c5a47f9582f9300 from master