[DependencyInjection] Add documentation about service decoration

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | yes (symfony/symfony#10600)
| Applies to    | 2.5+
| Fixed tickets | #3745
`foo` and `bar` are sooo confusing! Wouldn't it be better to use a real world example, let's say a `router` ?