Extend the docstring for obj_make_compatible() with examples

This adds to the docstring for obj_make_compatible() to help outline
the rules and scenarios to help developers understand what they need
to do in that method, and when.

Change-Id: Ifa8cb9a4f9a1a4d5afd0da4629a7d476a52c62d6
Merge "Extend the docstring for obj_make_compatible() with examples"