Shortening docstring preamble and moving text to the notes

[rcap107]

As reported in #1424, a lot of docstrings have extremely long preambles that make it hard to understand what the function/object is doing.

This PR addresses that issue by shortening a lot the head of the docstring: most of the info that is not necessary to understand how the function works is moved to either the examples or the Notes section.

This is a first iteration to improve the current status of the docstrings: later we might want to do a second pass and move some of what ends in the notes to the User Guide.