diff --git a/src/widgets/kernel/qopenglwidget.cpp b/src/widgets/kernel/qopenglwidget.cpp
index 8faa9f86819..c6c5e5bc80c 100644
--- a/src/widgets/kernel/qopenglwidget.cpp
+++ b/src/widgets/kernel/qopenglwidget.cpp
@@ -435,6 +435,23 @@ QT_BEGIN_NAMESPACE
   each frame. To restore the preserved behavior, call setUpdateBehavior() with
   \c PartialUpdate.
 
+  \section1 Alternatives
+
+  Adding a QOpenGLWidget into a window turns on OpenGL-based
+  compositing for the entire window.  In some special cases this may
+  not be ideal, and the old QGLWidget-style behavior with a separate,
+  native child window is desired. Desktop applications that understand
+  the limitations of this approach (for example when it comes to
+  overlaps, transparency, scroll views and MDI areas), can use
+  QOpenGLWindow with QWidget::createWindowContainer(). This is a
+  modern alternative to QGLWidget and is faster than QOpenGLWidget due
+  to the lack of the additional composition step. It is strongly
+  recommended to limit the usage of this approach to cases where there
+  is no other choice. Note that this option is not suitable for most
+  embedded and mobile platforms, and it is known to have issues on
+  certain desktop platforms (e.g. OS X) too. The stable,
+  cross-platform solution is always QOpenGLWidget.
+
   \e{OpenGL is a trademark of Silicon Graphics, Inc. in the United States and other
   countries.}