Doc: Fix template information for QAudioBuffer members

When QDoc parses a project, it parses the source code to extract the
user-provided documentation and perform sanity checkings based on the
code itself on it.

When QDoc parses an "\fn" command as part of this process, it tries to
understand, based on its intermediate representation built on the
information extracted from the code-base, which "documentable element"
the "\fn" refers to.

When QDoc performs this "matching" process, it takes into consideration
only a certain amount of information.
For example, no checking is performed over the template declaration of a
callable.

Due to some upcoming documentation, where two callables are
indistinguishable to the current process, as they differ only in their
template declaration, QDoc will start to take into consideration the
template declaration of a callable when matching.

This implies that an "\fn" command should now provide information
parity, with regards to template declaration for callables, with the
code-base so that QDoc can perform the match correctly.

The documentation for some of the members of `QAudioBuffer` is not in sync
with the intended target template declaration.

In particular, `QAudioBuffer` provides a public templated version and a
private non-templated version of `data`/`constData`.

The documentation for those member was provided as an auto-tying block
that was intended to tie to the private non-templated members, while
documenting both the private and non-private API.

As the private and public version only differ in their template
declaration, which was not previously considered, and in their return
type, which is correctly ignored when matching, QDoc would match the
documentation to the public templated version, even if in the code it
was positioned to match the private non-templated version.

Now that QDoc will consider the template information, the matching will
correctly pick the private non-templated version of the methods, thus
producing no documentation in the final output as private methods are
considered internal.

To fix the issue, the auto-tying documentation blocks for
`data`/`constData` were modified to use an `\fn` topic pointing to the
public templated version.

The body of the documentation was modified to avoid implying the
presence of two overloads for the methods, instead referring directly to
the public templated version, as the private version should not be
generally referred to in the final output.

Some spacing between the documentation blocks for `data`/`constData` and
the out-of-line definition of the private non-templated version of the
methods was added in the implementation file, so that it would be easier
to see that the documentation blocks are not intended to auto-tie to the
following definition.

A commment referring to QDoc inability to recognize both the templated
and non-templated version of the API was removed as it is soon going to
be out-of-date and is not relevant to the presented version of the
documentation anymore.

Task-number: QTBUG-118080
Change-Id: I2280098f76fd34567db8ec588615621643329fd0
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

1 files changed, 14 insertions, 16 deletions

diff --git a/src/multimedia/audio/qaudiobuffer.cpp b/src/multimedia/audio/qaudiobuffer.cpp
index 692da6282..69adcc5b7 100644
--- a/src/multimedia/audio/qaudiobuffer.cpp
+++ b/src/multimedia/audio/qaudiobuffer.cpp
@@ -214,15 +214,15 @@ qint64 QAudioBuffer::startTime() const noexcept
 }
 
 /*!
+    \fn template <typename T> const T* QAudioBuffer::constData() const
+
     Returns a pointer to this buffer's data.  You can only read it.
 
     This method is preferred over the const version of \l data() to
     prevent unnecessary copying.
 
-    There is also a templatized version of this constData() function that
-    allows you to retrieve a specific type of read-only pointer to
-    the data.  Note that there is no checking done on the format of
-    the audio buffer - this is simply a convenience function.
+    Note that there is no checking done on the format of the audio
+    buffer - this is simply a convenience function.
 
     \code
     // With a 16bit sample buffer:
@@ -230,6 +230,7 @@ qint64 QAudioBuffer::startTime() const noexcept
     \endcode
 
 */
+
 const void *QAudioBuffer::constData() const noexcept
 {
     if (!d)
@@ -238,14 +239,14 @@ const void *QAudioBuffer::constData() const noexcept
 }
 
 /*!
+    \fn template <typename T> const T* QAudioBuffer::data() const
+
     Returns a pointer to this buffer's data.  You can only read it.
 
     You should use the \l constData() function rather than this
     to prevent accidental deep copying.
 
-    There is also a templatized version of this data() function that
-    allows you to retrieve a specific type of read-only pointer to
-    the data.  Note that there is no checking done on the format of
+    Note that there is no checking done on the format of
     the audio buffer - this is simply a convenience function.
 
     \code
@@ -253,6 +254,7 @@ const void *QAudioBuffer::constData() const noexcept
     const quint16 *data = buffer->data<quint16>();
     \endcode
 */
+
 const void *QAudioBuffer::data() const noexcept
 {
     if (!d)
@@ -260,28 +262,24 @@ const void *QAudioBuffer::data() const noexcept
     return d->data.constData();
 }
 
-/*
-    Template data/constData functions caused override problems with qdoc,
-    so moved their docs into the non template versions.
-*/
-
 /*!
+    \fn template <typename T> T* QAudioBuffer::data()
+
     Returns a pointer to this buffer's data.  You can modify the
     data through the returned pointer.
 
     Since QAudioBuffer objects are explicitly shared, you should usually
     call detach() before modifying the data through this function.
 
-    There is also a templatized version of data() allows you to retrieve
-    a specific type of pointer to the data.  Note that there is no
-    checking done on the format of the audio buffer - this is
-    simply a convenience function.
+    Note that there is no checking done on the format of the audio
+    buffer - this is simply a convenience function.
 
     \code
     // With a 16bit sample buffer:
     quint16 *data = buffer->data<quint16>(); // May cause deep copy
     \endcode
 */
+
 void *QAudioBuffer::data()
 {
     if (!d)