lavc: document that avcodec_close() should not be used

We cannot deprecate it until the new parser API is in place, because of
the way libavformat works. But the majority of the users can already
simply replace it with avcodec_free_context(), which will simplify the
transition once it is finally deprecated.

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);