Dispatcher and @dispatch cannot be mixed - documentation should clearly state that

[Costor]

The documentation design.rst should clearly state that one must either use the approach using Dispatcher() or the approach using @dispatch. These two cannot be mixed.

Currently the example in Namespaces and dispatch merely states
# f = Dispatcher('f') # no need to create Dispatcher ahead of time

But actually in the sequence

f = Dispatcher('f')
@f.register(int)
def inc(x):
    return x + 1

@dispatch(float)
def f(x):
    return x - 1

the @dispatch overwrites f with a new Dispatcher object, and the registration f(int) is lost. This is by design: @dispatch uses the namespace to store names and definitions, while Dispatcher is unaware of namespaces.