Better document the behavior of decoding functions with respect to the BOM

[dralley]

As described on #88:

• decode() changes the encoding that's used according to the BOM and removes the BOM.
• decode_with_bom_removal() removes the (leading) BOM if it matches the BOM for the encoding but doesn't change the encoding.
• decode_without_bom_handling() gives no special treatment to the BOM.

The naming implies that the difference between decode() and decode_with_bom_removal() is that the latter removes the BOM whereas the former presumably would not. This isn't the case - both remove the bom, but decode() performs BOM sniffing whereas decode_with_bom_removal() does not, and that is the primary distinguishing feature between the two.

The documentation and perhaps naming of the functions could be improved to better reflect this (also applies to the streaming API - the decoder constructors of matching names).

[hsivonen]

Improved the docs. Thanks.