Fix example documentation for OpenGL module and (widget) Tools.

Change-Id: Id9dc39752bcae915f618e1a5696115a5e6923251
Reviewed-by: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@digia.com>

24 files changed, 71 insertions, 140 deletions

diff --git a/examples/opengl/doc/src/2dpainting.qdoc b/examples/opengl/doc/src/2dpainting.qdoc
index 24ff54b7ff..9059852add 100644
--- a/examples/opengl/doc/src/2dpainting.qdoc
+++ b/examples/opengl/doc/src/2dpainting.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example 2dpainting
     \title 2D Painting Example
+    \ingroup examples-widgets-opengl
 
     \brief The 2D Painting example shows how QPainter and QGLWidget can be used
     together to display accelerated 2D graphics on supported hardware.
diff --git a/examples/opengl/doc/src/cube.qdoc b/examples/opengl/doc/src/cube.qdoc
index 4885c59049..af82f2bb46 100644
--- a/examples/opengl/doc/src/cube.qdoc
+++ b/examples/opengl/doc/src/cube.qdoc
@@ -27,7 +27,7 @@
 
 /*!
     \example cube
-    \group all-examples
+    \ingroup examples-widgets-opengl
     \title Cube OpenGL ES 2.0 example
 
     \brief The Cube OpenGL ES 2.0 example shows how to write mouse rotateable
diff --git a/examples/opengl/doc/src/framebufferobject2.qdoc b/examples/opengl/doc/src/framebufferobject2.qdoc
index 96104d41a2..4014760d3e 100644
--- a/examples/opengl/doc/src/framebufferobject2.qdoc
+++ b/examples/opengl/doc/src/framebufferobject2.qdoc
@@ -29,6 +29,7 @@
     \example framebufferobject2
     \title Framebuffer Object 2 Example
 
+    \ingroup examples-widgets-opengl
     \brief The Framebuffer Object 2 example demonstrates how to use the
     QGLFramebufferObject class to render into an off-screen buffer and
     use the contents as a texture in a QGLWidget.
diff --git a/examples/opengl/doc/src/grabber.qdoc b/examples/opengl/doc/src/grabber.qdoc
index 5bcf8cc1bd..fa4915c7c9 100644
--- a/examples/opengl/doc/src/grabber.qdoc
+++ b/examples/opengl/doc/src/grabber.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example grabber
     \title Grabber Example
+    \ingroup examples-widgets-opengl
 
     \brief The Grabber examples shows how to retrieve the contents of an OpenGL framebuffer.
 
diff --git a/examples/opengl/doc/src/hellogl.qdoc b/examples/opengl/doc/src/hellogl.qdoc
index 3d513912c8..440141ef85 100644
--- a/examples/opengl/doc/src/hellogl.qdoc
+++ b/examples/opengl/doc/src/hellogl.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example hellogl
     \title Hello GL Example
+    \ingroup examples-widgets-opengl
 
     \brief The Hello GL example demonstrates the basic use of the OpenGL-related classes
     provided with Qt.
diff --git a/examples/opengl/doc/src/hellogl_es.qdoc b/examples/opengl/doc/src/hellogl_es.qdoc
deleted file mode 100644
index 6f31178768..0000000000
--- a/examples/opengl/doc/src/hellogl_es.qdoc
+++ /dev/null
@@ -1,128 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
-** Contact: http://www.qt-project.org/legal
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and Digia.  For licensing terms and
-** conditions see http://qt.digia.com/licensing.  For further information
-** use the contact form at http://qt.digia.com/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file.  Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
-    \example hellogl_es
-    \title Hello GL ES Example
-
-    \brief The Hello GL ES example is the \l{Hello GL Example} ported to OpenGL ES.
-    It also included some effects from the OpenGL \l{Overpainting Example}.
-
-    \image hellogl-es-example.png
-
-    A complete introduction to OpenGL ES and a description of all differences
-    between OpenGL and OpenGL ES is out of the scope of this document; but
-    we will describe some of the major issues and differences.
-
-    Since Hello GL ES is a direct port of standard OpenGL code, it is a fairly
-    good example for porting OpenGL code to OpenGL ES.
-
-    \tableofcontents
-
-    \section1 Using QGLWidget
-
-    QGLWidget can be used for OpenGL ES similar to the way it is used with
-    standard OpenGL; but there are some differences. We use EGL 1.0 to embedd
-    the OpenGL ES window within the native window manager. In
-    QGLWidget::initializeGL() we initialize OpenGL ES.
-
-    \section1 Porting OpenGL to OpenGL ES
-
-    Since OpenGL ES is missing the immediate mode and does not support quads,
-    we have to create triangle arrays.
-
-    We create a quad by adding vertices to a QList of vertices. We create both
-    sides of the quad and hardcode a distance of 0.05f. We also compute the
-    correct normal for each face and store them in another QList.
-
-    \snippet hellogl_es/glwidget.cpp 0
-
-    And then we convert the complete list of vertexes and the list of normals
-    into the native OpenGL ES format that we can use with the OpenGL ES API.
-
-    \snippet hellogl_es/glwidget.cpp 1
-
-    In \c paintQtLogo() we draw the triangle array using OpenGL ES. We use
-    q_vertexTypeEnum to abstract the fact that our vertex and normal arrays
-    are either in float or in fixed point format.
-
-    \snippet hellogl_es/glwidget.cpp 2
-
-    \section1 Using QGLPainter
-
-    Since the \c QGLPainter is slower for OpenGL ES we paint the bubbles with
-    the rasterizer and cache them in a QImage. This happends only once during
-    the initialiazation.
-
-    \snippet hellogl_es/bubble.cpp 0
-
-    For each bubble this QImage is then drawn to the QGLWidget by using the
-    according QPainter with transparency enabled.
-
-    \snippet hellogl_es/bubble.cpp 1
-
-    Another difference beetwen OpenGL and OpenGL ES is that OpenGL ES does not
-    support glPushAttrib(GL_ALL_ATTRIB_BITS). So we have to restore all the
-    OpenGL states ourselves, after we created the QPainter in
-    GLWidget::paintGL().
-
-    \snippet hellogl_es/glwidget.cpp 3
-
-    Setting up up the model view matrix and setting the right OpenGL states is
-    done in the same way as for standard OpenGL.
-
-    \snippet hellogl_es/glwidget.cpp 4
-
-    Now we have to restore the OpenGL state for the QPainter. This is not done
-    automatically for OpenGL ES.
-
-    \snippet hellogl_es/glwidget.cpp 5
-
-    Now we use the QPainter to draw the transparent bubbles.
-
-    \snippet hellogl_es/glwidget.cpp 6
-
-    In the end, we calculate the framerate and display it using the QPainter
-    again.
-
-    \snippet hellogl_es/glwidget.cpp 7
-
-    After we finished all the drawing operations we swap the screen buffer.
-
-    \snippet hellogl_es/glwidget.cpp 8
-
-    \section1 Summary
-
-    Similar to the \l{Hello GL Example}, we subclass QGLWidget to render
-    a 3D scene using OpenGL ES calls. QGLWidget is a subclass of QWidget.
-    Hence, its \l{QGLWidget}'s subclasses can be placed in layouts and
-    provided with interactive features just like normal custom widgets.
-
-    QGLWidget allows pure OpenGL ES rendering to be mixed with QPainter calls,
-    but care must be taken to maintain the state of the OpenGL ES
-    implementation.
-*/
diff --git a/examples/opengl/doc/src/overpainting.qdoc b/examples/opengl/doc/src/overpainting.qdoc
index 22ae4f874d..6a9be3d361 100644
--- a/examples/opengl/doc/src/overpainting.qdoc
+++ b/examples/opengl/doc/src/overpainting.qdoc
@@ -29,6 +29,7 @@
     \example overpainting
     \title Overpainting Example
 
+    \ingroup examples-widgets-opengl
     \brief The Overpainting example shows how QPainter can be used
     to overpaint a scene rendered using OpenGL in a QGLWidget.
 
diff --git a/examples/opengl/doc/src/pbuffers.qdoc b/examples/opengl/doc/src/pbuffers.qdoc
index 29f5b3c891..7994c59373 100644
--- a/examples/opengl/doc/src/pbuffers.qdoc
+++ b/examples/opengl/doc/src/pbuffers.qdoc
@@ -29,6 +29,7 @@
     \example pbuffers
     \title Pixel Buffers Example
 
+    \ingroup examples-widgets-opengl
     \brief The Pixel Buffers example demonstrates how to use the
     QGLPixelBuffer class to render into an off-screen buffer and use
     the contents as a dynamic texture in a QGLWidget.
diff --git a/examples/opengl/doc/src/pbuffers2.qdoc b/examples/opengl/doc/src/pbuffers2.qdoc
index 975feb5f0d..20a8de6caa 100644
--- a/examples/opengl/doc/src/pbuffers2.qdoc
+++ b/examples/opengl/doc/src/pbuffers2.qdoc
@@ -29,6 +29,7 @@
     \example pbuffers2
     \title Pixel Buffers 2 Example
 
+    \ingroup examples-widgets-opengl
     \brief The Pixel Buffers 2 example demonstrates how to use the
     QGLPixelBuffer class to render into an off-screen buffer and use
     the contents as a dynamic texture in a QGLWidget.
diff --git a/examples/opengl/doc/src/samplebuffers.qdoc b/examples/opengl/doc/src/samplebuffers.qdoc
index 7891b71acc..d20a36860c 100644
--- a/examples/opengl/doc/src/samplebuffers.qdoc
+++ b/examples/opengl/doc/src/samplebuffers.qdoc
@@ -29,6 +29,7 @@
     \example samplebuffers
     \title Sample Buffers Example
 
+    \ingroup examples-widgets-opengl
     \brief The Sample Buffers example demonstrates how to use and enable
     sample buffers in a QGLWidget.
 
diff --git a/examples/opengl/doc/src/textures.qdoc b/examples/opengl/doc/src/textures.qdoc
index 390272ac9c..6fdcbfc598 100644
--- a/examples/opengl/doc/src/textures.qdoc
+++ b/examples/opengl/doc/src/textures.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example textures
     \title Textures Example
+    \ingroup examples-widgets-opengl
 
     \brief The Textures example demonstrates the use of Qt's image classes as textures in
     applications that use both OpenGL and Qt to display graphics.
diff --git a/examples/widgets/doc/src/completer.qdoc b/examples/widgets/doc/src/completer.qdoc
index baa3a55ea6..a2a6d2fc52 100644
--- a/examples/widgets/doc/src/completer.qdoc
+++ b/examples/widgets/doc/src/completer.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example tools/completer
     \title Completer Example
+    \ingroup example-widgets-tools
 
     \brief The Completer example shows how to provide string-completion facilities
     for an input widget based on data provided by a model.
diff --git a/examples/widgets/doc/src/echoplugin.qdoc b/examples/widgets/doc/src/echoplugin.qdoc
index 1ab29c1c39..52247bbb65 100644
--- a/examples/widgets/doc/src/echoplugin.qdoc
+++ b/examples/widgets/doc/src/echoplugin.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example tools/echoplugin
     \title Echo Plugin Example
+    \group examples-widgets-tools
 
     \brief This example shows how to create a Qt plugin.
 
diff --git a/examples/widgets/doc/src/i18n.qdoc b/examples/widgets/doc/src/i18n.qdoc
index 0b38abf34a..ae97a4869b 100644
--- a/examples/widgets/doc/src/i18n.qdoc
+++ b/examples/widgets/doc/src/i18n.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example tools/i18n
     \title I18N Example
+    \ingroup examples-widgets-tools
 
     \brief The Internationalization (I18N) example demonstrates Qt's support for translated
     text. Developers can write the initial application text in one language, and
diff --git a/examples/widgets/doc/src/plugandpaint.qdoc b/examples/widgets/doc/src/plugandpaint.qdoc
index a9d3f7cf27..88433a5e2f 100644
--- a/examples/widgets/doc/src/plugandpaint.qdoc
+++ b/examples/widgets/doc/src/plugandpaint.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example tools/plugandpaint
     \title Plug & Paint Example
+    \ingroup examples-widgets-tools
 
     \brief The Plug & Paint example demonstrates how to write Qt
     applications that can be extended through plugins.
diff --git a/examples/widgets/doc/src/regexp.qdoc b/examples/widgets/doc/src/regexp.qdoc
index 9c9957e28a..07143f6350 100644
--- a/examples/widgets/doc/src/regexp.qdoc
+++ b/examples/widgets/doc/src/regexp.qdoc
@@ -28,6 +28,7 @@
 /*! 
     \example tools/regexp
     \title Regular Expressions Example
+    \ingroup example-widgets-tools
 
     \brief The Regular Expressions (RegExp) example shows how regular expressions in Qt are
     applied to text by providing an environment in which new regular expressions can be
diff --git a/examples/widgets/doc/src/settingseditor.qdoc b/examples/widgets/doc/src/settingseditor.qdoc
index 1f7a8b271b..5fdc1ba00a 100644
--- a/examples/widgets/doc/src/settingseditor.qdoc
+++ b/examples/widgets/doc/src/settingseditor.qdoc
@@ -28,6 +28,7 @@
 /*! 
     \example tools/settingseditor
     \title Settings Editor Example
+    \ingroup examples-widgets-tools
 
     \brief The Settings Editor example shows how Qt's standard settings support is used in an
     application by providing an editor that enables the user to view the settings for
diff --git a/examples/widgets/doc/src/styleplugin.qdoc b/examples/widgets/doc/src/styleplugin.qdoc
index 158f1d4769..615ca0f0bf 100644
--- a/examples/widgets/doc/src/styleplugin.qdoc
+++ b/examples/widgets/doc/src/styleplugin.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example tools/styleplugin
     \title Style Plugin Example
+    \ingroup examples-widgets-tools
 
     \brief This example shows how to create a plugin that extends Qt with a new
     GUI look and feel.
diff --git a/examples/widgets/doc/src/treemodelcompleter.qdoc b/examples/widgets/doc/src/treemodelcompleter.qdoc
index 1d204907aa..9e74cad88e 100644
--- a/examples/widgets/doc/src/treemodelcompleter.qdoc
+++ b/examples/widgets/doc/src/treemodelcompleter.qdoc
@@ -1,4 +1,4 @@
-/****************************************************************************
+	/****************************************************************************
 **
 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
@@ -28,6 +28,7 @@
 /*!
     \example tools/treemodelcompleter
     \title Tree Model Completer Example
+    \ingroup examples-widgets-tools
 
     \brief The Tree Model Completer example shows how to provide completion
     facilities for a hierarchical model, using a period as the separator
diff --git a/examples/widgets/doc/src/undo.qdoc b/examples/widgets/doc/src/undo.qdoc
index f802aa4ffb..b2dd9c51b2 100644
--- a/examples/widgets/doc/src/undo.qdoc
+++ b/examples/widgets/doc/src/undo.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example tools/undo
     \title Undo Framework
+    \ingroup examples-widgets-tools
 
     \brief This example shows Qt's undo framework in action.
 
diff --git a/examples/widgets/doc/src/undoframework.qdoc b/examples/widgets/doc/src/undoframework.qdoc
index d0aaa785d2..3ed1ed290b 100644
--- a/examples/widgets/doc/src/undoframework.qdoc
+++ b/examples/widgets/doc/src/undoframework.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example tools/undoframework
     \title Undo Framework Example
+    \ingroup examples-widgets-tools
 
     \brief This example shows how to implement undo/redo functionality
     with the Qt undo framework.
diff --git a/src/opengl/doc/images/opengl-examples.png b/src/opengl/doc/images/opengl-examples.png
new file mode 100644
index 0000000000..8acdf8cabd
--- /dev/null
+++ b/src/opengl/doc/images/opengl-examples.png
diff --git a/src/opengl/doc/src/qtopengl-examples.qdoc b/src/opengl/doc/src/qtopengl-examples.qdoc
new file mode 100644
index 0000000000..2ad4f27404
--- /dev/null
+++ b/src/opengl/doc/src/qtopengl-examples.qdoc
@@ -0,0 +1,46 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \ingroup all-examples
+    \title OpenGL Examples from the Qt OpenGL module
+    \brief Accessing OpenGL from Qt.
+    \group examples-widgets-opengl
+
+    \image opengl-examples.png
+
+    These examples describe how to use the Qt OpenGL Module. For new code,
+    please use the OpenGL classes in the \l {Qt GUI Module}.
+   
+
+    Qt provides support for integration with OpenGL implementations on all
+    platforms, giving developers the opportunity to display hardware accelerated
+    3D graphics alongside a more conventional user interface.
+
+    These examples demonstrate the basic techniques used to take advantage of
+    OpenGL in Qt applications.
+*/
diff --git a/src/widgets/doc/src/qtwidgets-examples.qdoc b/src/widgets/doc/src/qtwidgets-examples.qdoc
index 05402d98bc..b321942a70 100644
--- a/src/widgets/doc/src/qtwidgets-examples.qdoc
+++ b/src/widgets/doc/src/qtwidgets-examples.qdoc
@@ -26,10 +26,10 @@
 ****************************************************************************/
 
 /*!
-    \page qtwidgets-examples.html
     \title Qt Widgets Examples
     \brief Lots of examples of how to use different kinds of widgets.
     \ingroup all-examples
+    \group examples-widgets
 
     \image widget-examples.png
 
@@ -43,12 +43,9 @@
     be used to change the appearance of standard widgets and appropriately
     written custom widgets.
 
-    \annotatedlist examples-widgets
-
 */
 
 /*!
-    \page examples-painting.html
     \ingroup all-examples
     \title Painting Examples
     \brief How to use the Qt painting system.
@@ -56,19 +53,17 @@
 
     \image painting-examples.png
 
-    Qt's painting system is able to render vector graphics, images, and outline
-    font-based text with sub-pixel accuracy accuracy using anti-aliasing to
-    improve rendering quality.
+    Qt's painting system is able to render vector graphics, images,
+    and outline font-based text with sub-pixel accuracy using
+    anti-aliasing to improve rendering quality.
 
     These examples show the most common techniques that are used when painting
     with Qt, from basic concepts such as drawing simple primitives to the use of
     transformations.
 
-    \annotatedlist{painting-examples}
 */
 
 /*!
-    \page examples-richtext.html
     \ingroup all-examples
     \title Rich Text Examples
     \brief Using the document-oriented rich text engine.
@@ -84,7 +79,6 @@
  */
 
 /*!
-    \page examples-desktop.html
     \ingroup all-examples
     \title Desktop Examples
     \brief Integrating your Qt application with your favorite desktop.