Docs: clarify the relation between default alpha and format.

Reformat the new API docs the get rid of the unnecessary stars.

And fix some typos.

Change-Id: I09dcb3bea55cfd7b9209a4e0ad43e28a47fd1fa4
Reviewed-by: Shawn Rutledge <shawn.rutledge@digia.com>
Reviewed-by: Gunnar Sletta <gunnar.sletta@jollamobile.com>

1 files changed, 72 insertions, 64 deletions

diff --git a/src/quick/items/qquickwindow.cpp b/src/quick/items/qquickwindow.cpp
index de8eb115dc..3b20241e08 100644
--- a/src/quick/items/qquickwindow.cpp
+++ b/src/quick/items/qquickwindow.cpp
@@ -3446,10 +3446,14 @@ bool QQuickWindow::hasDefaultAlphaBuffer()
     \brief \a useAlpha specifies whether to use alpha transparency on newly created windows.
     \since 5.1
 
-    In any application which expects to create translucent windows, it's
-    necessary to set this to true before creating the first QQuickWindow,
-    because all windows will share the same \l QOpenGLContext. The default
-    value is false.
+    In any application which expects to create translucent windows, it's necessary to set
+    this to true before creating the first QQuickWindow. The default value is false.
+
+    \note This function affects the size of the alpha buffer in the format returned by
+    defaultFormat(). Enabling alpha via this function and passing a format with alpha
+    buffer size 8 to setDefaultFormat() are equivalent.
+
+    \sa hasDefaultAlphaBuffer(), setDefaultFormat(), defaultFormat()
  */
 void QQuickWindow::setDefaultAlphaBuffer(bool useAlpha)
 {
@@ -3519,26 +3523,26 @@ void QQuickWindow::resetOpenGLState()
 }
 
 /*!
- * \brief QQuickWindow::setDefaultFormat
- * \since 5.4
- * @brief Sets the global default surface format that is used for all new QQuickWindow instances.
- *
- * While it is possible to specify a QSurfaceFormat for every QQuickWindow by
- * calling the member function setFormat(), windows may also be created from
- * QML by using the Window and ApplicationWindow elements. In this case there
- * is no C++ code involved in the creation of the window instance, yet
- * applications may still wish to set certain surface format values, for
- * example to request a given OpenGL version or profile. Such applications can
- * call this static functions in main(). \a format will be used for all Quick
- * windows created afterwards.
- *
- * \note The default value for the default format is not necessarily a
- * default-constructed QSurfaceFormat. It may already have depth, stencil and alpha
- * buffer sizes set. Unless there is a need to change all these sizes, the format should
- * first be queried via defaultFormat() and the changes should be applied to that,
- * instead of merely starting with default-constructed QSurfaceFormat.
- *
- * \sa setFormat(), format(), defaultFormat()
+    \brief QQuickWindow::setDefaultFormat
+    \since 5.4
+    @brief Sets the global default surface format that is used for all new QQuickWindow instances.
+
+    While it is possible to specify a QSurfaceFormat for every QQuickWindow by
+    calling the member function setFormat(), windows may also be created from
+    QML by using the Window and ApplicationWindow elements. In this case there
+    is no C++ code involved in the creation of the window instance, yet
+    applications may still wish to set certain surface format values, for
+    example to request a given OpenGL version or profile. Such applications can
+    call this static functions in main(). \a format will be used for all Quick
+    windows created afterwards.
+
+    \note The default value for the default format is not necessarily a
+    default-constructed QSurfaceFormat. It may already have depth, stencil and alpha
+    buffer sizes set. Unless there is a need to change all these sizes, the format should
+    first be queried via defaultFormat() and the changes should be applied to that,
+    instead of merely starting with a default-constructed QSurfaceFormat.
+
+    \sa setFormat(), format(), defaultFormat()
  */
 void QQuickWindow::setDefaultFormat(const QSurfaceFormat &format)
 {
@@ -3547,10 +3551,14 @@ void QQuickWindow::setDefaultFormat(const QSurfaceFormat &format)
 }
 
 /*!
- * \brief QQuickWindow::defaultFormat
- * \since 5.4
- * \return The global default surface format that is used for all QQuickWindow instances.
- * \note This function requires a QGuiApplication or QApplication instance.
+    \brief QQuickWindow::defaultFormat
+    \since 5.4
+
+    \return The global default surface format that is used for all QQuickWindow instances.
+
+    \note This function requires a QGuiApplication or QApplication instance.
+
+    \sa setDefaultFormat()
  */
 QSurfaceFormat QQuickWindow::defaultFormat()
 {
@@ -3562,28 +3570,28 @@ QSurfaceFormat QQuickWindow::defaultFormat()
 }
 
 /*!
- * \brief QQuickWindow::glslVersion
- * \since 5.4
- * \return The OpenGL Shading Language version for this window.
- *
- * QML components that need to be usable on different platforms and environments may need
- * to deal with different OpenGL versions if they include ShaderEffect items. The source
- * code for a given shader may not be compatible with an OpenGL context that targets a
- * different OpenGL version or profile, hence it might be necessary to provide multiple
- * versions of the shader. This property helps in deciding which shader source should be
- * chosen.
- *
- * The value corresponds to GLSL version declarations, for example an OpenGL 4.2 core
- * profile context will result in the value \e{420 core}, while an OpenGL ES 3.0 context
- * gives \e{300 es}. For OpenGL (ES) 2 the value will be an empty string since the
- * corresponding shading language does not use version declarations.
- *
- * \note The value does not necessarily indicate that the shader source must target that
- * specific version. For example, compatibility profiles and ES 3.x all allow using
- * OpenGL 2 style shaders. The most important for reusable components is to check for
- * core profiles since these do not accept shaders with the old syntax.
- *
- * \sa setFormat(), glslIsCoreProfile()
+    \brief QQuickWindow::glslVersion
+    \since 5.4
+    \return The OpenGL Shading Language version for this window.
+
+    QML components that need to be usable on different platforms and environments may need
+    to deal with different OpenGL versions if they include ShaderEffect items. The source
+    code for a given shader may not be compatible with an OpenGL context that targets a
+    different OpenGL version or profile, hence it might be necessary to provide multiple
+    versions of the shader. This property helps in deciding which shader source should be
+    chosen.
+
+    The value corresponds to GLSL version declarations, for example an OpenGL 4.2 core
+    profile context will result in the value \e{420 core}, while an OpenGL ES 3.0 context
+    gives \e{300 es}. For OpenGL (ES) 2 the value will be an empty string since the
+    corresponding shading language does not use version declarations.
+
+    \note The value does not necessarily indicate that the shader source must target that
+    specific version. For example, compatibility profiles and ES 3.x all allow using
+    OpenGL 2 style shaders. The most important for reusable components is to check for
+    core profiles since these do not accept shaders with the old syntax.
+
+    \sa setFormat(), setDefaultFormat(), glslIsCoreProfile()
  */
 QString QQuickWindow::glslVersion() const
 {
@@ -3621,20 +3629,20 @@ QString QQuickWindow::glslVersion() const
 }
 
 /*!
- * \brief QQuickWindow::glslIsCoreProfile
- * \since 5.4
- * \return True if the window is rendering using OpenGL core profile.
- *
- * This is convenience function to check if the window's OpenGL context is a core profile
- * context. It is more efficient to perform the check via this function than parsing the
- * string returned from glslVersion().
- *
- * Resusable QML components will typically use this function in bindings in order to
- * choose between core and non core profile compatible shader sources.
- *
- * To retrieve more information about the shading language, use glslVersion().
- *
- * \sa glslVersion()
+    \brief QQuickWindow::glslIsCoreProfile
+    \since 5.4
+    \return True if the window is rendering using OpenGL core profile.
+
+    This is convenience function to check if the window's OpenGL context is a core profile
+    context. It is more efficient to perform the check via this function than parsing the
+    string returned from glslVersion().
+
+    Resusable QML components will typically use this function in bindings in order to
+    choose between core and non core profile compatible shader sources.
+
+    To retrieve more information about the shading language, use glslVersion().
+
+    \sa glslVersion(), setFormat(), setDefaultFormat()
  */
 bool QQuickWindow::glslIsCoreProfile() const
 {