From 01d8abdbf1bdeed9efe706318c5798c4f1e9b104 Mon Sep 17 00:00:00 2001 From: Marc Mutz Date: Mon, 4 Jan 2016 22:39:46 +0100 Subject: [docs] Gently steer people away from QPair Change-Id: Ib0fb69f856606612d516426732f619422630c93f Reviewed-by: Friedemann Kleint Reviewed-by: Lars Knoll --- src/corelib/doc/snippets/code/doc_src_qpair.cpp | 9 +++++++++ src/corelib/tools/qpair.qdoc | 12 ++++++++++++ 2 files changed, 21 insertions(+) diff --git a/src/corelib/doc/snippets/code/doc_src_qpair.cpp b/src/corelib/doc/snippets/code/doc_src_qpair.cpp index 1473d3bd4f..85dc1cdac7 100644 --- a/src/corelib/doc/snippets/code/doc_src_qpair.cpp +++ b/src/corelib/doc/snippets/code/doc_src_qpair.cpp @@ -48,6 +48,15 @@ pair.first = "pi"; pair.second = 3.14159265358979323846; //! [1] +//! [struct] +struct Variable { + QString name; + double value; +}; +Variable v; +v.name = "pi"; +v.value = 3.14159265358979323846; +//! [struct] //! [2] QList > list; diff --git a/src/corelib/tools/qpair.qdoc b/src/corelib/tools/qpair.qdoc index 7cba7480f0..cc0aa731fb 100644 --- a/src/corelib/tools/qpair.qdoc +++ b/src/corelib/tools/qpair.qdoc @@ -48,6 +48,18 @@ \snippet code/doc_src_qpair.cpp 1 + Note, however, that it is almost always preferable to define a small struct + to hold the result of a function with multiple return values. A struct + trivially generalizes to more than two values, and allows more descriptive + member names than \c{first} and \c{second}: + + \snippet code/doc_src_qpair.cpp struct + + The advent of C++11 automatic variable type deduction (\c{auto}) shifts the + emphasis from the type name to the name of functions and members. Thus, QPair, + like \c{std::pair} and \c{std::tuple}, is mostly useful in generic (template) + code, where defining a dedicated type is not possible. + QPair's template data types (T1 and T2) must be \l{assignable data types}. You cannot, for example, store a QWidget as a value; instead, store a QWidget *. A few functions have additional -- cgit v1.2.3