Exclude Path Decorator for Class in Quickstart

[href]

As mentioned in #451:

• Quickstart's HelloWorld code walkthrough, point 3:

  We then set up a Root class. Morepath is model-driven and in order to create any views, we first need at least one model, in this case the empty Root class.

  I struggled with it a little later when, throughout the next chapters, the @App.path directives are decorating functions instead of classes. To finally get the whole picture I had to intentionally go read that bit in the technical documentation, where its application to the class constructor is stated. Therefore I propose adding an aside (like the myriad of useful ones already populating pervasively the documentation) explaining this detail (duality of use) when the path directive is first used (i.e. in the code walkthrough referenced above).

I personally rarely use the path decorator outside of test-cases. I think it's a valid use-case and we should at some point explain it. But my immediate instinct is to not decorate the root class directly in the Quickstart example. I think using a function for a path is the more canonical example of how the path decorator should be used in Morepath. So I wouldn't focus on it in the Quickstart example.

[faneca]

I don't think there's anything wrong with letting that example be as it is. If you were to write the same by using a function instead of a class (and please correct me if I'm wrong as I'm the newbie here), instead of

@App.path(path='')
class Root(object):
    pass

you'll end up with something like

class Root(object):
    pass

@App.path(path='', model=Root)
def root():
    return Root()

This second approach is the way to go when you split your project into several files (when following the cookiecutter template, for instance)... but for a so simple example, it makes sense to use the former one. The problem IMHO is not having a good explanation there for the two use cases: one, needing an explicit model, applied to functions, and another, without an explicit model parameter, applied to classes, which is equivalent to applying it to the class' constructor.