Update API (#457)

* explicitly define `BROTLI_BOOL` to be `int`
 * add `BROTLI_` prefix to `MAKE_UINT64_T` macros
 * replace `true`/`false`/`1`/`0` mentions with `BROTLI_TRUE`/`FALSE`
 * add `BrotliEncoderSetParameter` documentation
 * add explicit caution to `BrotliEncoderMaxCompressedSize`
 * fix formatting in `port.h`

5 files changed, 57 insertions, 51 deletions

diff --git a/enc/entropy_encode_static.h b/enc/entropy_encode_static.h
index 2449c30..bc0ee53 100644
--- a/enc/entropy_encode_static.h
+++ b/enc/entropy_encode_static.h
@@ -83,7 +83,7 @@ static const uint32_t kCodeLengthBits[18] = {
 static BROTLI_INLINE void StoreStaticCodeLengthCode(
     size_t* storage_ix, uint8_t* storage) {
   BrotliWriteBits(
-      40, MAKE_UINT64_T(0x0000ffU, 0x55555554U), storage_ix, storage);
+      40, BROTLI_MAKE_UINT64_T(0x0000ffU, 0x55555554U), storage_ix, storage);
 }
 
 static const uint64_t kZeroRepsBits[BROTLI_NUM_COMMAND_SYMBOLS] = {
@@ -516,7 +516,7 @@ static const uint16_t kStaticCommandCodeBits[BROTLI_NUM_COMMAND_SYMBOLS] = {
 static BROTLI_INLINE void StoreStaticCommandHuffmanTree(
     size_t* storage_ix, uint8_t* storage) {
   BrotliWriteBits(
-      56, MAKE_UINT64_T(0x926244U, 0x16307003U), storage_ix, storage);
+      56, BROTLI_MAKE_UINT64_T(0x926244U, 0x16307003U), storage_ix, storage);
   BrotliWriteBits(3, 0x00000000U, storage_ix, storage);
 }
 
diff --git a/include/brotli/decode.h b/include/brotli/decode.h
index 75cac3c..b4415af 100755
--- a/include/brotli/decode.h
+++ b/include/brotli/decode.h
@@ -135,8 +135,8 @@ BROTLI_DEC_API void BrotliDecoderSetCustomDictionary(
     BrotliDecoderState* s, size_t size,
     const uint8_t dict[BROTLI_ARRAY_PARAM(size)]);
 
-/* Returns true, if decoder has some unconsumed output.
-   Otherwise returns false. */
+/* Returns BROTLI_TRUE, if decoder has some unconsumed output.
+   Otherwise returns BROTLI_FALSE. */
 BROTLI_DEC_API BROTLI_BOOL BrotliDecoderHasMoreOutput(
     const BrotliDecoderState* s);
 
@@ -156,12 +156,12 @@ BROTLI_DEC_API BROTLI_BOOL BrotliDecoderHasMoreOutput(
 BROTLI_DEC_API const uint8_t* BrotliDecoderTakeOutput(
     BrotliDecoderState* s, size_t* size);
 
-/* Returns true, if decoder has already received some input bytes.
-   Otherwise returns false. */
+/* Returns BROTLI_TRUE, if decoder has already received some input bytes.
+   Otherwise returns BROTLI_FALSE. */
 BROTLI_DEC_API BROTLI_BOOL BrotliDecoderIsUsed(const BrotliDecoderState* s);
 
-/* Returns true, if decoder is in a state where we reached the end of the input
-   and produced all of the output; returns false otherwise. */
+/* Returns BROTLI_TRUE, if decoder is in a state where we reached the end of the
+   input and produced all of the output; returns BROTLI_FALSE otherwise. */
 BROTLI_BOOL BrotliDecoderIsFinished(const BrotliDecoderState* s);
 
 /* Returns detailed error code after BrotliDecoderDecompressStream returns
diff --git a/include/brotli/encode.h b/include/brotli/encode.h
index 44d436e..75736f0 100755
--- a/include/brotli/encode.h
+++ b/include/brotli/encode.h
@@ -69,6 +69,13 @@ typedef enum BrotliEncoderParameter {
 /* A state can not be reused for multiple brotli streams. */
 typedef struct BrotliEncoderStateStruct BrotliEncoderState;
 
+/* Sets the specified parameter to the given encoder instance.
+   Returns BROTLI_FALSE if parameter is unrecognized, or value is invalid.
+   Returns BROTLI_FALSE if value of parameter can not be changed at current
+   encoder state (e.g. when encoding is started, window size might be already
+   encoded and therefore it is impossible to change it).
+   Returns BROTLI_TRUE if value is accepted. CAUTION: invalid values might be
+   accepted in case they would not break encoding process. */
 BROTLI_ENC_API BROTLI_BOOL BrotliEncoderSetParameter(
     BrotliEncoderState* state, BrotliEncoderParameter p, uint32_t value);
 
@@ -100,11 +107,11 @@ BROTLI_DEPRECATED BROTLI_ENC_API void BrotliEncoderCopyInputToRingBuffer(
    the new output meta-block, or to zero if no new output meta-block has been
    created (in this case the processed input data is buffered internally).
    If |*out_size| is positive, |*output| points to the start of the output
-   data. If |is_last| or |force_flush| is 1, an output meta-block is always
-   created. However, until |is_last| is 1 encoder may retain up to 7 bits
-   of the last byte of output. To force encoder to dump the remaining bits
-   use WriteMetadata() to append an empty meta-data block.
-   Returns false if the size of the input data is larger than
+   data. If |is_last| or |force_flush| is BROTLI_TRUE, an output meta-block is
+   always created. However, until |is_last| is BROTLI_TRUE encoder may retain up
+   to 7 bits of the last byte of output. To force encoder to dump the remaining
+   bits use WriteMetadata() to append an empty meta-data block.
+   Returns BROTLI_FALSE if the size of the input data is larger than
    input_block_size(). */
 BROTLI_DEPRECATED BROTLI_ENC_API BROTLI_BOOL BrotliEncoderWriteData(
     BrotliEncoderState* state, const BROTLI_BOOL is_last,
@@ -121,6 +128,9 @@ BROTLI_ENC_API void BrotliEncoderSetCustomDictionary(
 
 /* Returns buffer size that is large enough to contain BrotliEncoderCompress
    output for any input.
+   CAUTION: result is not applicable to BrotliEncoderCompressStream output,
+   because every "flush" adds extra overhead bytes, and some encoder settings
+   (e.g. quality 0 and 1) might imply a "soft flush" after every chunk of input.
    Returns 0 if result does not fit size_t. */
 BROTLI_ENC_API size_t BrotliEncoderMaxCompressedSize(size_t input_size);
 
@@ -132,7 +142,7 @@ BROTLI_ENC_API size_t BrotliEncoderMaxCompressedSize(size_t input_size);
    If compression fails, |*encoded_size| is set to 0.
    If BrotliEncoderMaxCompressedSize(|input_size|) is not zero, then
    |*encoded_size| is never set to the bigger value.
-   Returns false if there was an error and true otherwise. */
+   Returns BROTLI_FALSE if there was an error and BROTLI_TRUE otherwise. */
 BROTLI_ENC_API BROTLI_BOOL BrotliEncoderCompress(
     int quality, int lgwin, BrotliEncoderMode mode, size_t input_size,
     const uint8_t input_buffer[BROTLI_ARRAY_PARAM(input_size)],
@@ -175,7 +185,7 @@ BROTLI_ENC_API BROTLI_BOOL BrotliEncoderCompress(
    WARNING: when flushing and finishing, |op| should not change until operation
    is complete; input stream should not be refilled as well.
 
-   Returns false if there was an error and true otherwise.
+   Returns BROTLI_FALSE if there was an error and BROTLI_TRUE otherwise.
 */
 BROTLI_ENC_API BROTLI_BOOL BrotliEncoderCompressStream(
     BrotliEncoderState* s, BrotliEncoderOperation op, size_t* available_in,
@@ -185,12 +195,13 @@ BROTLI_ENC_API BROTLI_BOOL BrotliEncoderCompressStream(
 /* Check if encoder is in "finished" state, i.e. no more input is acceptable and
    no more output will be produced.
    Works only with BrotliEncoderCompressStream workflow.
-   Returns 1 if stream is finished and 0 otherwise. */
+   Returns BROTLI_TRUE if stream is finished and BROTLI_FALSE otherwise. */
 BROTLI_ENC_API BROTLI_BOOL BrotliEncoderIsFinished(BrotliEncoderState* s);
 
 /* Check if encoder has more output bytes in internal buffer.
    Works only with BrotliEncoderCompressStream workflow.
-   Returns 1 if has more output (in internal buffer) and 0 otherwise. */
+   Returns BROTLI_TRUE if has more output (in internal buffer) and BROTLI_FALSE
+   otherwise. */
 BROTLI_ENC_API BROTLI_BOOL BrotliEncoderHasMoreOutput(BrotliEncoderState* s);
 
 /* Returns pointer to internal output buffer.
diff --git a/include/brotli/port.h b/include/brotli/port.h
index 3613893..da4461c 100755
--- a/include/brotli/port.h
+++ b/include/brotli/port.h
@@ -88,25 +88,25 @@ OR:
 #endif
 
 #if defined(BROTLI_SHARED_COMPILATION) && defined(_WIN32)
-  #if defined(BROTLICOMMON_SHARED_COMPILATION)
-    #define BROTLI_COMMON_API __declspec(dllexport)
-  #else
-    #define BROTLI_COMMON_API __declspec(dllimport)
-  #endif
-  #if defined(BROTLIDEC_SHARED_COMPILATION)
-    #define BROTLI_DEC_API __declspec(dllexport)
-  #else
-    #define BROTLI_DEC_API __declspec(dllimport)
-  #endif
-  #if defined(BROTLIENC_SHARED_COMPILATION)
-    #define BROTLI_ENC_API __declspec(dllexport)
-  #else
-    #define BROTLI_ENC_API __declspec(dllimport)
-  #endif
-#else /* defined (_WIN32) */
- #define BROTLI_COMMON_API
- #define BROTLI_DEC_API
- #define BROTLI_ENC_API
+#if defined(BROTLICOMMON_SHARED_COMPILATION)
+#define BROTLI_COMMON_API __declspec(dllexport)
+#else
+#define BROTLI_COMMON_API __declspec(dllimport)
+#endif  /* BROTLICOMMON_SHARED_COMPILATION */
+#if defined(BROTLIDEC_SHARED_COMPILATION)
+#define BROTLI_DEC_API __declspec(dllexport)
+#else
+#define BROTLI_DEC_API __declspec(dllimport)
+#endif  /* BROTLIDEC_SHARED_COMPILATION */
+#if defined(BROTLIENC_SHARED_COMPILATION)
+#define BROTLI_ENC_API __declspec(dllexport)
+#else
+#define BROTLI_ENC_API __declspec(dllimport)
+#endif  /* BROTLIENC_SHARED_COMPILATION */
+#else  /* BROTLI_SHARED_COMPILATION && _WIN32 */
+#define BROTLI_COMMON_API
+#define BROTLI_DEC_API
+#define BROTLI_ENC_API
 #endif
 
 #ifndef _MSC_VER
diff --git a/include/brotli/types.h b/include/brotli/types.h
index c3508b8..1a388f2 100755
--- a/include/brotli/types.h
+++ b/include/brotli/types.h
@@ -24,23 +24,18 @@ typedef __int64 int64_t;
 #include <stdint.h>
 #endif  /* defined(_MSC_VER) && (_MSC_VER < 1600) */
 
-#if (!defined(_MSC_VER) || (_MSC_VER >= 1800)) && \
-    (defined(__cplusplus) || \
-        (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L))
-#include <stdbool.h>
-#define BROTLI_BOOL bool
-#define BROTLI_TRUE true
-#define BROTLI_FALSE false
-#define TO_BROTLI_BOOL(X) (!!(X))
-#else
-typedef enum {
-  BROTLI_FALSE = 0,
-  BROTLI_TRUE = !BROTLI_FALSE
-} BROTLI_BOOL;
+/* BROTLI_BOOL is a portable "bool" replacement. For input parameters it is
+   preferrable either use BROTLI_TRUE and BROTLI_FALSE macros, or convert
+   boolean expression with TO_BROTLI_BOOL macros.
+   Return values should not be tested for equality with "true", "false",
+   "BROTLI_TRUE", "BROTLI_FALSE", but rather be evaluated, for example:
+   `if (foo(enc) && !bar(dec) { bool x = !!baz(enc); }` */
+#define BROTLI_BOOL int
+#define BROTLI_TRUE 1
+#define BROTLI_FALSE 0
 #define TO_BROTLI_BOOL(X) (!!(X) ? BROTLI_TRUE : BROTLI_FALSE)
-#endif
 
-#define MAKE_UINT64_T(high, low) ((((uint64_t)(high)) << 32) | low)
+#define BROTLI_MAKE_UINT64_T(high, low) ((((uint64_t)(high)) << 32) | low)
 
 #define BROTLI_UINT32_MAX (~((uint32_t)0))
 #define BROTLI_SIZE_MAX (~((size_t)0))