Current docstring provides incorrect description of to_replace argument:
If the value is a dict, then `value` is ignored and `to_replace` must be a mapping from column name (string) to replacement value.
It looks like it has been copied from `na.fill` docs. In fact dict should provide mapping from value to replacement value.
Moreover docs fail to explain some fundamental limitations (like lack of support for heterogeneous values) and some usage scenarios.