-/* Same as encoding_guess_tail_encoding() but returns true for UTF-8 or false
- for the fallback encoding. */
-bool
+/* Returns an encoding guess based on ENCODING and the N bytes of text starting
+ at DATA. DATA should start with the first non-ASCII text character (as
+ determined by encoding_guess_is_ascii_text()) found in the input.
+
+ The return value is:
+
+ 0, if the encoding is definitely not UTF-8 (because the input contains
+ byte sequences that are not valid in UTF-8).
+
+ 1, if the encoding appears to be UTF-8 (because the input contains valid
+ UTF-8 multibyte sequences).
+
+ -1, if the input contains only ASCII characters. (This means that the
+ input may be treated as UTF-8, since ASCII is a subset of UTF-8.)
+
+ See encoding-guesser.h for intended use of this function.
+
+ N must be at least ENCODING_GUESS_MIN, unless the file has fewer bytes than
+ that starting with the first non-ASCII text character. */
+int