doc: Expand and organize Decorate documentation (#858)
doc: Expand and organize Decorate documentation (#858)

This elaborates on the documentation for fx.Decorate with more examples,
and organizes it into two sections:

- Decorator functions, enumerating the various signatures a decorator
  function can have
- Decorator scope, explaining how decorator changes are scoped

Added demonstrative examples for everything.
In the future, we can turn some of these into example tests.

Refs GO-1254
uber-go/fx,uber-go/fx