diff --git a/src/opengl/qgl.cpp b/src/opengl/qgl.cpp
index 6476e2b26c..71f1bd2b54 100644
--- a/src/opengl/qgl.cpp
+++ b/src/opengl/qgl.cpp
@@ -3786,7 +3786,7 @@ void QGLWidget::setFormat(const QGLFormat &format)
     attributes that were requested.
 */
 
-/*
+/*!
   \fn void QGLWidget::setContext(QGLContext *context,
                                  const QGLContext* shareContext,
                                  bool deleteOldContext)
@@ -3812,6 +3812,12 @@ void QGLWidget::setFormat(const QGLFormat &format)
   to the old context (as returned by context()), and want to restore
   that context later.
 
+  \note This function is obsolete and should no longer be used. If you were
+  using it to recreate the context for a QGLWidget, you should instead create a
+  new QGLWidget or use the QOpenGLContext API in conjunction with QWindow.
+  There is currently no officially supported way to substitute QGLWidget's
+  context with your own implementation of QGLContext.
+
   \sa context(), isSharing()
 */