diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 18db7c55d9..d8e56caeac 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -3415,6 +3415,9 @@ int avcodec_get_context_defaults3(AVCodecContext *s, AVCodec *codec);
  * @param codec if non-NULL, allocate private data and initialize defaults
  *              for the given codec. It is illegal to then call avcodec_open2()
  *              with a different codec.
+ *              If NULL, then the codec-specific defaults won't be initialized,
+ *              which may result in suboptimal default settings (this is
+ *              important mainly for encoders, e.g. libx264).
  *
  * @return An AVCodecContext filled with default values or NULL on failure.
  * @see avcodec_get_context_defaults