Doc: Mark QSet::toList, QSet::fromList, QList::toSet, QList::fromSet as obsolete

They got deprecated in code already in 92f98427326. Make sure they
are marked as deprecated in the documenation, too, and give examples
on what to use instead.

Change-Id: I003020a44cbc6187dc813796c7f93f9f9d93bf0b
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

2 files changed, 92 insertions, 31 deletions

diff --git a/src/corelib/tools/qlist.cpp b/src/corelib/tools/qlist.cpp
index c0b0912249..eb5a06bb33 100644
--- a/src/corelib/tools/qlist.cpp
+++ b/src/corelib/tools/qlist.cpp
@@ -2017,7 +2017,7 @@ void **QListData::erase(void **xi)
 
     \include containers-range-constructor.qdocinc
 
-    \sa fromSet(), toVector(), QVector::toList()
+    \sa toVector(), QVector::toList()
 */
 
 /*! \fn template <class T> QVector<T> QList<T>::toVector() const
@@ -2030,61 +2030,91 @@ void **QListData::erase(void **xi)
 
     \include containers-range-constructor.qdocinc
 
-    \sa toSet(), fromVector(), QVector::fromList()
+    \sa  fromVector(), QVector::fromList()
 */
 
 /*! \fn template <class T> QList<T> QList<T>::fromSet(const QSet<T> &set)
+    \obsolete
 
     Returns a QList object with the data contained in \a set. The
     order of the elements in the QList is undefined.
 
-    Example:
-
-    \snippet code/src_corelib_tools_qlistdata.cpp 23
-
     \include containers-range-constructor.qdocinc
 
-    \sa fromVector(), toSet(), QSet::toList()
+    \oldcode
+    QSet<int> set;
+    // ...
+    QList<int> list = QList<int>::fromSet(set);
+    \newcode
+    QSet<int> set;
+    // ...
+    QList<int> list(set.begin(), set.end());
+    \endcode
+
+    \sa QList(InputIterator, InputIterator), fromVector(), toSet(), QSet::toList()
 */
 
 /*! \fn template <class T> QSet<T> QList<T>::toSet() const
+    \obsolete
 
     Returns a QSet object with the data contained in this QList.
     Since QSet doesn't allow duplicates, the resulting QSet might be
     smaller than the original list was.
 
-    Example:
-
-    \snippet code/src_corelib_tools_qlistdata.cpp 24
-
     \include containers-range-constructor.qdocinc
 
-    \sa toVector(), fromSet(), QSet::fromList()
+    \oldcode
+    QStringList list;
+    // ...
+    QSet<QString> set = list.toSet();
+    \newcode
+    QStringList list;
+    // ...
+    QSet<QString> set(list.begin(), list.end());
+    \endcode
+
+    \sa QSet::QSet(InputIterator, InputIterator), toVector(), fromSet(), QSet::fromList()
 */
 
 /*! \fn template <class T> QList<T> QList<T>::fromStdList(const std::list<T> &list)
+    \obsolete
 
     Returns a QList object with the data contained in \a list. The
     order of the elements in the QList is the same as in \a list.
 
-    Example:
-
-    \snippet code/src_corelib_tools_qlistdata.cpp 25
-
     \include containers-range-constructor.qdocinc
 
-    \sa toStdList(), QVector::fromStdVector()
+    \oldcode
+    std::list<double> stdlist;
+    // ...
+    QList<double> list = QList<double>::fromStdList(stdlist);
+    \newcode
+    std::list<double> stdlist;
+    // ...
+    QList<double> list(stdlist.begin(), stdlist.end());
+    \endcode
+
+    \sa QList(InputIterator, InputIterator), toStdList(), QVector::fromStdVector()
 */
 
 /*! \fn template <class T> std::list<T> QList<T>::toStdList() const
+    \obsolete
 
     Returns a std::list object with the data contained in this QList.
     Example:
 
-    \snippet code/src_corelib_tools_qlistdata.cpp 26
-
     \include containers-range-constructor.qdocinc
 
+    \oldcode
+    QList<double> list;
+    // ...
+    std::list<double> stdlist = list.toStdList();
+    \newcode
+    QList<double> list;
+    // ...
+    std::list<double> stdlist(list.begin(), list.end());
+    \endcode
+
     \sa fromStdList(), QVector::toStdVector()
 */
 
diff --git a/src/corelib/tools/qset.qdoc b/src/corelib/tools/qset.qdoc
index 42dd1288ac..dcd6de3d5c 100644
--- a/src/corelib/tools/qset.qdoc
+++ b/src/corelib/tools/qset.qdoc
@@ -1071,17 +1071,32 @@
 */
 
 /*! \fn template <class T> QList<T> QSet<T>::toList() const
+    \obsolete
 
     Returns a new QList containing the elements in the set. The
     order of the elements in the QList is undefined.
 
-    Example:
+    \include containers-range-constructor.qdocinc
 
-    \snippet code/doc_src_qset.cpp 13
+    \oldcode
+    QSet<QString> set;
+    // ...
+    QList<QString> list = set.toList();
+    \newcode
+    QSet<QString> set;
+    // ...
+    QList<QString> list(set.begin(), set.end());
+    \endcode
 
-    \include containers-range-constructor.qdocinc
+    or
 
-    \sa fromList(), QList::fromSet()
+    \code
+    QSet<QString> set;
+    // ...
+    QList<QString> list = set.values();
+    \endcode
+
+    \sa QList::QList(InputIterator, InputIterator), values(), fromList(), QList::fromSet()
 */
 
 /*! \fn template <class T> QList<T> QSet<T>::values() const
@@ -1089,28 +1104,44 @@
     Returns a new QList containing the elements in the set. The
     order of the elements in the QList is undefined.
 
-    This is the same as toList().
-
     \include containers-range-constructor.qdocinc
 
-    \sa fromList(), QList::fromSet()
+    \oldcode
+    QSet<QString> set;
+    // ...
+    QList<QString> list = set.values();
+    \newcode
+    QSet<QString> set;
+    // ...
+    QList<QString> list(set.begin(), set.end());
+    \endcode
+
+
+    \sa QList::QList(InputIterator, InputIterator)
 */
 
 
 /*! \fn template <class T> QSet<T> QSet<T>::fromList(const QList<T> &list)
+    \obsolete
 
     Returns a new QSet object containing the data contained in \a
     list. Since QSet doesn't allow duplicates, the resulting QSet
     might be smaller than the \a list, because QList can contain
     duplicates.
 
-    Example:
-
-    \snippet code/doc_src_qset.cpp 14
-
     \include containers-range-constructor.qdocinc
 
-    \sa toList(), QList::toSet()
+    \oldcode
+    QStringList list;
+    // ...
+    QSet<QString> set = QSet<QString>::fromList(list);
+    \newcode
+    QStringList list;
+    // ...
+    QSet<QString> set(list.begin(), list.end());
+    \endcode
+
+    \sa QSet(InputIterator, InputIterator), values(), QList::toSet()
 */
 
 /*!