The docstring to the utility function make_decorator provides the example of customized_count = some_decorator(count). However, the correct usage should be customized_count = some_decorator()(count) otherwise we actually get dec(gen_func) as the decorated function, rather than dec_inner(...) as intended.

Description

The equivalent syntactic-sugar version of customized_count = some_decorator(count) would be

@some_decorator
def customized_count(...):
   ...

This is a common python pattern for decorators that do not require arguments.

However, the wrappers that are turned into decorators may accept additional arguments and so what comes back from make_decorator needs to be a decorator factory. The syntactic-sugar version would then be something like:

@some_decorator(arg0, kwargs0=...)
def customized_count(...):
   ...

This is the version that make_decorator() produces, and is also how the usage is described in the curated documentation for plans: @relative_set_decorator([motor]).

The equivalent without the sugar is customized_count = some_decorator()(count).

Motivation and Context

This PR will update the docstring for make_decorator to match the curated documentation, and provide the correct usage for the resulting decorators.

If the instructions are followed as previously written, there is no mechanism to provide arguments to the original wrapper, and any attempt to call the decorated plan results in the following error:

>>> plan = customized_count([], num=6)
TypeError: make_decorator.<locals>.dec_outer.<locals>.dec() got an unexpected keyword argument 'num'

(the original plan accepts a keyword argument num).

How Has This Been Tested?

I added wrappers to some common functions. If I use count = baseline_decorator(count) I get the error described above. If I change this to count = baseline_decorator(devices=[...])(count, ...). I do not get the error.

I have not tested whether the messages for the baseline are actually applied.