add a little detail to custom repr method docs

- explicitly state the return type, rather than only via example
- give some examples of PNG, HTML
- note that formatters shouldn't be sensitive to other formats

docs/source/config/integrating.rst

@@ -26,11 +26,13 b' Rich display'
 
 Custom methods
 ----------------------
+
 IPython can display richer representations of objects.
 To do this, you can define ``_ipython_display_()``, or any of a number of 
 ``_repr_*_()`` methods. 
 Note that these are surrounded by single, not double underscores.
 
+
 .. list-table:: Supported ``_repr_*_`` methods
    :widths: 20 15 15 15
    :header-rows: 1
@@ -76,7 +78,17 b' Note that these are surrounded by single, not double underscores.'
      - ?
      - ?
 
-If the methods don't exist, or return ``None``, the standard ``repr()`` is used.
+If the methods don't exist, the standard ``repr()`` is used.
+If a method exists and returns ``None``, it is treated the same as if it does not exist.
+In general, *all* available formatters will be called when an object is displayed,
+and it is up to the UI to select which to display.
+A given formatter should not generally change its output based on what other formats are available -
+that should be handled at a different level, such as the :class:`~.DisplayFormatter`, or configuration.
+
+``_repr_*_`` methods should *return* data of the expected format and have no side effects.
+For example, ``_repr_html_`` should return HTML as a `str` and ``_repr_png_`` should return PNG data as `bytes`.
+
+If you wish to take control of display via your own side effects, use ``_ipython_display_()``.
 
 For example::