Improve Documentation Slightly

diff --git a/lib/zstd.h b/lib/zstd.h
index e42a4bd493bdfeb7815eab7733fe7f59fc606027..f8d5e84da1cfda28d036c6be8ceff9479f112c90 100644 (file)
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -1548,15 +1548,16 @@ ZSTDLIB_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const void* pre
 #define ZSTD_c_srcSizeHint ZSTD_c_experimentalParam7
 
 /* Controls whether the new and experimental "dedicated dictionary search
- * structure" can be used.
+ * structure" can be used. This feature is still rough around the edges, be
+ * prepared for surprising behavior!
  *
  * How to use it:
  *
  * When using a CDict, whether to use this feature or not is controlled at
  * CDict creation, and it must be set in a CCtxParams set passed into that
- * construction. A compression will then use the feature or not based on how
- * the CDict was constructed; the value of this param, set in the CCtx, will
- * have no effect.
+ * construction (via ZSTD_createCDict_advanced2()). A compression will then
+ * use the feature or not based on how the CDict was constructed; the value of
+ * this param, set in the CCtx, will have no effect.
  *
  * However, when a dictionary buffer is passed into a CCtx, such as via
  * ZSTD_CCtx_loadDictionary(), this param can be set on the CCtx to control
@@ -1578,10 +1579,13 @@ ZSTDLIB_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const void* pre
  * written as the compression goes along. This means we can choose a search
  * structure for the dictionary that is read-optimized.
  *
- * This feature enables the use of that different structure. Note that this
- * means that the CDict tables can no longer be copied into the CCtx, so
- * the dict attachment mode ZSTD_dictForceCopy will no longer be useable. The
- * dictionary can only be attached or reloaded.
+ * This feature enables the use of that different structure.
+ *
+ * Note that some of the members of the ZSTD_compressionParameters struct have
+ * different semantics and constraints in the dedicated search structure. It is
+ * highly recommended that you simply set a compression level in the CCtxParams
+ * you pass into the CDict creation call, and avoid messing with the cParams
+ * directly.
  *
  * Effects:
  *
@@ -1589,9 +1593,13 @@ ZSTDLIB_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const void* pre
  * implementation supports this feature. Currently, that's limited to
  * ZSTD_greedy, ZSTD_lazy, and ZSTD_lazy2.
  *
- * In general, you should expect compression to be faster, and CDict creation
- * to be slightly slower. Eventually, we will probably make this mode the
- * default.
+ * Note that this means that the CDict tables can no longer be copied into the
+ * CCtx, so the dict attachment mode ZSTD_dictForceCopy will no longer be
+ * useable. The dictionary can only be attached or reloaded.
+ *
+ * In general, you should expect compression to be faster--sometimes very much
+ * so--and CDict creation to be slightly slower. Eventually, we will probably
+ * make this mode the default.
  */
 #define ZSTD_c_enableDedicatedDictSearch ZSTD_c_experimentalParam8