Describe how string literals are handled (#96)

README.md

@@ -159,7 +159,7 @@ def very_important_function(
     debug: bool = False,
 ):
     """Applies `variables` to the `template` and writes to `file`."""
-    with open(file, 'w') as f:
+    with open(file, "w") as f:
         ...
 ```
 
@@ -260,6 +260,15 @@ if you'd like a trailing comma in this situation and *Black* didn't
 recognize it was safe to do so, put it there manually and *Black* will
 keep it.
 
+### Strings
+
+*Black* prefers double quotes (`"` and `"""`), but only if this does not
+result in more escaping. It will remove escape sequences as necessary as
+part of moving to the other type of quote. This applies to all kinds of
+prefixed strings, including *raw-strings* (`r""`), *byte literals* (`b""`),
+and *formatted strings* (`f""`). The approach above strikes a good balance
+between consistency and legibility.
+
 
 ## Editor integration
 

black.py

@@ -1815,6 +1815,13 @@ def normalize_prefix(leaf: Leaf, *, inside_brackets: bool) -> None:
 
 
 def normalize_string_quotes(leaf: Leaf) -> None:
+    """Prefer double quotes but only if it doesn't cause more escaping.
+
+    Adds or removes backslashes as appropriate. Doesn't parse and fix
+    strings nested in f-strings (yet).
+
+    Note: Mutates its argument.
+    """
     value = leaf.value.lstrip("furbFURB")
     if value[:3] == '"""':
         return

docs/reference/reference_functions.rst

@@ -77,6 +77,8 @@ Utilities
 
 .. autofunction:: black.normalize_prefix
 
+.. autofunction:: black.normalize_string_quotes
+
 .. autofunction:: black.preceding_leaf
 
 .. autofunction:: black.whitespace