Enhance CustomMapping documentation

[eerhardt]

See discussion #2569 (comment)

this is definitely something we'll want to document very carefully. It is a bit odd, this pattern of mutable input as a return value. (I of course know exactly why we do it, but a user will not.)

We should ensure we explain (in the cookbook, docs.microsoft.com, or otherwise) how this pattern works, and give the reasons why we do it like this.

/cc @TomFinley

[eerhardt]

Also, we should add some <see tags to and from CustomMappingEstimator.

See #2569 (comment) for the suggestion.

[artidoro]

We added samples for the custom mapping estimator and improved the documentation.
If you feel that this should be improved further please reopen the issue and specify what we should add.