Add documentation for `register_strwidth_error` and `string` functions

powerline/lib/unicode.py

@@ -58,6 +58,27 @@ last_swe_idx = 0
 
 
 def register_strwidth_error(strwidth):
+	'''Create new encode errors handling method similar to ``replace``
+
+	Like ``replace`` this method uses question marks in place of the characters 
+	that cannot be represented in the requested encoding. Unlike ``replace`` the 
+	amount of question marks is identical to the amount of display cells 
+	offending character occupies. Thus encoding ``…`` (U+2026, HORIZONTAL 
+	ELLIPSIS) to ``latin1`` will emit one question mark, but encoding ``Ａ`` 
+	(U+FF21, FULLWIDTH LATIN CAPITAL LETTER A) will emit two question marks.
+
+	Since width of some characters depends on the terminal settings and 
+	powerline knows how to respect them a single error handling method cannot be 
+	used. Instead of it the generator function is used which takes ``strwidth`` 
+	function (function that knows how to compute string width respecting all 
+	needed settings) and emits new error handling method name.
+
+	:param function strwidth:
+		Function that computs string width measured in display cells the string 
+		occupies when displayed.
+
+	:return: New error handling method name.
+	'''
 	global last_swe_idx
 	last_swe_idx += 1
 
@@ -141,6 +162,20 @@ else:
 			return s
 
 
+string.__doc__ = (
+	'''Transform ``unicode`` or ``bytes`` object into ``str`` object
+
+	On Python-2 this encodes ``unicode`` to ``bytes`` (which is ``str``) using 
+	UTF-8 encoding; on Python-3 this decodes ``bytes`` to ``unicode`` (which is 
+	``str``) using UTF-8 encoding.
+
+	Useful for functions that expect an ``str`` object in both unicode versions, 
+	not caring about the semantic differences between them in Python-2 and 
+	Python-3.
+	'''
+)
+
+
 def surrogate_pair_to_character(high, low):
 	'''Transform a pair of surrogate codepoints to one codepoint
 	'''