[gtk+/wip/ebassi/legacy-gl: 5/5] docs: Improve description of gdk_gl_context_is_legacy()

[Emmanuele Bassi <ebassi src gnome org>]

commit d1ecb62e2d8b5ae14347b9b922ec59ec6752af63
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Wed Oct 7 08:50:23 2015 +0100

    docs: Improve description of gdk_gl_context_is_legacy()
    
    Explain why this function is available, and why you may need it.

 gdk/gdkglcontext.c |   15 ++++++++++++++-
 1 files changed, 14 insertions(+), 1 deletions(-)
---
diff --git a/gdk/gdkglcontext.c b/gdk/gdkglcontext.c
index d7420e9..06cd019 100644
--- a/gdk/gdkglcontext.c
+++ b/gdk/gdkglcontext.c
@@ -564,7 +564,20 @@ gdk_gl_context_get_required_version (GdkGLContext *context,
  *
  * Whether the #GdkGLContext is in legacy mode or not.
  *
- * The #GdkGLContext must be realized.
+ * The #GdkGLContext must be realized before calling this function.
+ *
+ * When realizing a GL context, GDK will try to use the OpenGL 3.2 core
+ * profile; this profile removes all the OpenGL API that was deprecated
+ * prior to the 3.2 version of the specification. If the realization is
+ * successful, this function will return %FALSE.
+ *
+ * If the underlying OpenGL implementation does not support core profiles,
+ * GDK will fall back to a pre-3.2 compatibility profile, and this function
+ * will return %TRUE.
+ *
+ * You can use the value returned by this function to decide which kind
+ * of OpenGL API to use, or whether to do extension discovery, or what
+ * kind of shader programs to load.
  *
  * Returns: %TRUE if the GL context is in legacy mode
  *