doc: Fixed several qdoc warnings.

All the qdoc errors are fixed in QStringBuilder, but because the
class is a template class and uses strange templates, qdoc gets
very confused, and the resulting documentation for QStringBuilder
is not complete and accurate. To fix this correctly will require
changes to the qdoc program.

3 files changed, 45 insertions, 36 deletions

diff --git a/src/corelib/tools/qstringbuilder.cpp b/src/corelib/tools/qstringbuilder.cpp
index a01b58c..17e2cec 100644
--- a/src/corelib/tools/qstringbuilder.cpp
+++ b/src/corelib/tools/qstringbuilder.cpp
@@ -70,49 +70,43 @@
     NULL char.
 */
 
-/*! \fn QLatin1Literal::QLatin1Literal(const char(&string)[N])
+/*! \fn QLatin1Literal::QLatin1Literal(const char str)
  
-    Constructs a new literal from the given \a string.
+    Constructs a new literal from the string \a str.
 */
 
-/*! \fn char *QLatin1Literal::data() const
+/*! \fn const char *QLatin1Literal::data() const
  
     Returns a pointer to the first character of the string literal.
     The string literal is terminated by a NUL character.
 */
 
-/*! \fn QLatin1Literal::operator QString() const
- 
-    Converts the \c QLatin1Literal into a \c QString object.
-*/
-
-
-
 /*!
     \class QStringBuilder
     \reentrant
     \since 4.6
 
-    \brief The QStringBuilder class is a template class that provides a facility to build
-    up QStrings from smaller chunks.
+    \brief The QStringBuilder class is a template class that provides a facility to build up QStrings from smaller chunks.
 
     \ingroup tools
     \ingroup shared
     \ingroup text
     \mainclass
 
-    When creating strings from smaller chunks, typically \c QString::operator+()
-    is used, resulting in \e{n - 1} reallocations when operating on \e{n} chunks.
+    To build a QString by multiple concatenations, QString::operator+()
+    is typically used. This causes \e{n - 1} reallocations when building
+    a string from \e{n} chunks.
 
-    QStringBuilder uses expression templates to collect the individual parts,
-    compute the total size, allocate memory for the resulting QString object,
-    and copy the contents of the chunks into the result.
+    QStringBuilder uses expression templates to collect the individual
+    chunks, compute the total size, allocate the required amount of
+    memory for the final QString object, and copy the chunks into the
+    allocated memory.
 
-    The QStringBuilder class is not to be used explicitly in user code.
-    Instances of the class are created as return values of the operator%()
-    function, acting on objects of type \c QString, \c QLatin1String,
-    \c QLatin1Literal, \c \QStringRef, \c QChar, \c QCharRef,
-    \c QLatin1Char, and \c char.
+    The QStringBuilder class is not to be used explicitly in user
+    code.  Instances of the class are created as return values of the
+    operator%() function, acting on objects of type QString,
+    QLatin1String, QLatin1Literal, QStringRef, QChar, QCharRef,
+    QLatin1Char, and \c char.
 
     Concatenating strings with operator%() generally yields better
     performance then using \c QString::operator+() on the same chunks
@@ -122,7 +116,11 @@
     \sa QLatin1Literal, QString
 */
 
-/* \fn template <class A, class B> QStringBuilder<A, B> operator%(const A &a, const B &b)
+/*! \fn QStringBuilder::QStringBuilder(const A &a, const B &b)
+  Constructs a QStringBuilder from \a a and \a b.
+ */
+
+/* \fn QStringBuilder::operator%(const A &a, const B &b)
 
     Returns a \c QStringBuilder object that is converted to a QString object
     when assigned to a variable of QString type or passed to a function that
@@ -133,3 +131,13 @@
     \c QChar, \c QCharRef, \c QLatin1Char, and \c char.
 */
 
+/*! \fn QByteArray QStringBuilder::toLatin1() const
+  Returns a Latin-1 representation of the string as a QByteArray.  The
+  returned byte array is undefined if the string contains non-Latin1
+  characters.
+ */
+
+/*! \fn QStringBuilder::operator QString() const
+ 
+    Converts the \c QLatin1Literal into a \c QString object.
+*/
diff --git a/src/corelib/tools/qstringbuilder.h b/src/corelib/tools/qstringbuilder.h
index c63dc7b..19f14b4 100644
--- a/src/corelib/tools/qstringbuilder.h
+++ b/src/corelib/tools/qstringbuilder.h
@@ -56,11 +56,12 @@ QT_MODULE(Core)
 class QLatin1Literal
 {
 public:
-    template <int N>
-    QLatin1Literal(const char (&str)[N]) : m_size(N - 1), m_data(str) {}
+    int size() const { return m_size; }
+    const char *data() const { return m_data; }
 
-    inline int size() const { return m_size; }
-    inline const char *data() const { return m_data; }
+    template <int N>
+    QLatin1Literal(const char (&str)[N]) 
+        : m_size(N - 1), m_data(str) {}
 
 private:
     const int m_size;
diff --git a/src/gui/styles/qproxystyle.cpp b/src/gui/styles/qproxystyle.cpp
index 54e6831..589ca9c 100644
--- a/src/gui/styles/qproxystyle.cpp
+++ b/src/gui/styles/qproxystyle.cpp
@@ -54,23 +54,23 @@ QT_BEGIN_NAMESPACE
     \class QProxyStyle
 
     \brief The QProxyStyle class is a convenience class that simplifies
-    the overriding of QStyle elements.
+    dynamically overriding QStyle elements.
 
     \since 4.6
 
     A QProxyStyle wraps a QStyle (usually the default system style) for the
-    purpose of overriding the painting or other specific behavior of the
-    wrapped style.
+    purpose of dynamically overriding painting or other specific style behavior.
 
-    Below is an example that overrides the shortcut underline
-    behavior on all platforms:
+    The following example shows how to override the shortcut underline
+    behavior on any platform:
 
     \snippet doc/src/snippets/code/src_gui_qproxystyle.cpp 1
 
-    Warning: Although Qt's internal styles should respect this hint,
-    there is no guarantee that it will work for all styles. It would
-    not work on a Mac, for example, because menus are handled by the
-    operating system on the Mac.
+    Warning: The \l {QCommonStyle} {common styles} provided by Qt will
+    respect this hint, because they call QStyle::proxy(), but there is
+    no guarantee that QStyle::proxy() will be called for user defined
+    or system controlled styles. It would not work on a Mac, for
+    example, where menus are handled by the operating system.
 
     \sa QStyle
 */