diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 24cf39f324..dc6649af54 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -3756,6 +3756,11 @@ int avcodec_open2(AVCodecContext *avctx, const AVCodec *codec, AVDictionary **op
  * Calling this function on an AVCodecContext that hasn't been opened will free
  * the codec-specific data allocated in avcodec_alloc_context3() with a non-NULL
  * codec. Subsequent calls will do nothing.
+ *
+ * @note Do not use this function. Use avcodec_free_context() to destroy a
+ * codec context (either open or closed). Opening and closing a codec context
+ * multiple times is not supported anymore -- use multiple codec contexts
+ * instead.
  */
 int avcodec_close(AVCodecContext *avctx);