Which note? If it's .. note:: then that should probably just be folded into the first line, something like A decorator to add a 'data' kwarg to any a function; also does some input sanitation
(yes, this was my fault...sorry)

No, it is the numpydoc section "Notes".
I don't think appending anything would work as expected anyways, as it would be in the wrong section.

You can see the effect it has by comparing the rendered version of scatter: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.scatter
and the docstring in a terminal (or looking at the code). There are two Notes section, and the last one "overwrites" the first one.

Note that the the docstring.Appender also doesn't work as it should in the rendering.
(@docstring.Appender("Addition kwargs: hold = [True|False] overrides default hold state", "\n") shows up at the end of the docstring instead of the of correct section).

Because of all this is very none standard, it makes it hard to identify where the problem comes from.

I have opened a bug on numpydoc for this issue (it should not have been undetected for so long):
numpy/numpydoc#64

This is actually critical to having a reasonably polished 2.0. One way to fix it might be to use string interpolation instead of appending the "data" doc block. This would have the advantage of providing full control over where that paragraph goes. It's not clear to me it really belongs in the Notes section anyway.
I agree with @NelleV in being uncomfortable with all the complexity in the present system--not to mention the horrible mess that the interpolated tables of mostly useless artist kwargs leave--but overhauling it is a big project. For 2.0 we must continue to patch it up in its present form. (It might be possible to improve it a little, by using a link instead of endlessly repeating the Line2D kwargs table. And the next incremental improvement would be to replace that automatically-generated table with a less nutty hand-written one. And the next...)

I can fix this by manually updating the different docstrings of that section to reflect the categorical input and remove the automatic appending of the notes section.
It would be a good occasion to add examples as well.

One step closer to 2.0…