From 395a19f0325e883749dde76849bd1092a711d802 Mon Sep 17 00:00:00 2001 From: Oswald Buddenhagen Date: Thu, 12 Apr 2018 21:10:59 +0200 Subject: improve documentation, mostly of the QT_TR*_NOOP macros MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change-Id: I65ccddec84a01945a6aee2a859d4f92ea830785b Reviewed-by: Paul Wicking Reviewed-by: Topi Reiniö Reviewed-by: Mateusz Starzycki Reviewed-by: Martin Smith --- .../snippets/code/src_corelib_global_qglobal.cpp | 16 +++--- src/corelib/global/qglobal.cpp | 58 +++++++++++----------- src/corelib/global/qglobal.h | 2 +- 3 files changed, 38 insertions(+), 38 deletions(-) (limited to 'src/corelib') diff --git a/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp b/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp index ceb3f8adf3..2d7b9a9ac8 100644 --- a/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp @@ -387,11 +387,11 @@ CONFIG += no_keywords //! [34] QString FriendlyConversation::greeting(int type) { -static const char *greeting_strings[] = { - QT_TR_NOOP("Hello"), - QT_TR_NOOP("Goodbye") -}; -return tr(greeting_strings[type]); + static const char *greeting_strings[] = { + QT_TR_NOOP("Hello"), + QT_TR_NOOP("Goodbye") + }; + return tr(greeting_strings[type]); } //! [34] @@ -410,7 +410,7 @@ QString FriendlyConversation::greeting(int type) QString global_greeting(int type) { return qApp->translate("FriendlyConversation", - greeting_strings[type]); + greeting_strings[type]); } //! [35] @@ -434,8 +434,8 @@ QString FriendlyConversation::greeting(int type) QString global_greeting(int type) { return qApp->translate("FriendlyConversation", - greeting_strings[type].source, - greeting_strings[type].comment); + greeting_strings[type].source, + greeting_strings[type].comment); } //! [36] diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp index 30c80b8b6f..21f22a32ba 100644 --- a/src/corelib/global/qglobal.cpp +++ b/src/corelib/global/qglobal.cpp @@ -648,10 +648,10 @@ Q_STATIC_ASSERT((std::is_same::value)); compiler or platform specific code to their application. The remaining macros are convenience macros for larger operations: - The QT_TRANSLATE_NOOP() and QT_TR_NOOP() macros provide the - possibility of marking text for dynamic translation, - i.e. translation without changing the stored source text. The - Q_ASSERT() and Q_ASSERT_X() enables warning messages of various + The QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRANSLATE_NOOP3() + macros provide the possibility of marking strings for delayed + translation. + The Q_ASSERT() and Q_ASSERT_X() enables warning messages of various level of refinement. The Q_FOREACH() and foreach() macros implement Qt's foreach loop. @@ -662,11 +662,11 @@ Q_STATIC_ASSERT((std::is_same::value)); memory, if the pointer is 0. The qPrintable() and qUtf8Printable() macros represent an easy way of printing text. - Finally, the QT_POINTER_SIZE macro expands to the size of a - pointer in bytes, and the QT_VERSION and QT_VERSION_STR macros - expand to a numeric value or a string, respectively, specifying - Qt's version number, i.e the version the application is compiled - against. + The QT_POINTER_SIZE macro expands to the size of a pointer in bytes. + + The macros QT_VERSION and QT_VERSION_STR expand to a numeric value + or a string, respectively, that specifies the version of Qt that the + application is compiled against. \sa , QSysInfo */ @@ -3676,19 +3676,18 @@ bool qunsetenv(const char *varName) \macro QT_TR_NOOP(sourceText) \relates - Marks the string literal \a sourceText for dynamic translation in - the current context (class), i.e the stored \a sourceText will not - be altered. + Marks the UTF-8 encoded string literal \a sourceText for delayed + translation in the current context (class). - The macro expands to \a sourceText. + The macro tells lupdate to collect the string, and expands to + \a sourceText itself. Example: \snippet code/src_corelib_global_qglobal.cpp 34 - The macro QT_TR_NOOP_UTF8() is identical except that it tells lupdate - that the source string is encoded in UTF-8. Corresponding variants - exist in the QT_TRANSLATE_NOOP() family of macros, too. + The macro QT_TR_NOOP_UTF8() is identical and obsolete; this applies + to all other _UTF8 macros as well. \sa QT_TRANSLATE_NOOP(), {Internationalization with Qt} */ @@ -3697,12 +3696,12 @@ bool qunsetenv(const char *varName) \macro QT_TRANSLATE_NOOP(context, sourceText) \relates - Marks the string literal \a sourceText for dynamic translation in - the given \a context; i.e, the stored \a sourceText will not be - altered. The \a context is typically a class and also needs to - be specified as string literal. + Marks the UTF-8 encoded string literal \a sourceText for delayed + translation in the given \a context. The \a context is typically + a class name and also needs to be specified as a string literal. - The macro expands to \a sourceText. + The macro tells lupdate to collect the string, and expands to + \a sourceText itself. Example: @@ -3712,18 +3711,19 @@ bool qunsetenv(const char *varName) */ /*! - \macro QT_TRANSLATE_NOOP3(context, sourceText, comment) + \macro QT_TRANSLATE_NOOP3(context, sourceText, disambiguation) \relates \since 4.4 - Marks the string literal \a sourceText for dynamic translation in the - given \a context and with \a comment, i.e the stored \a sourceText will - not be altered. The \a context is typically a class and also needs to - be specified as string literal. The string literal \a comment - will be available for translators using e.g. Qt Linguist. + Marks the UTF-8 encoded string literal \a sourceText for delayed + translation in the given \a context with the given \a disambiguation. + The \a context is typically a class and also needs to be specified + as a string literal. The string literal \a disambiguation should be + a short semantic tag to tell apart otherwise identical strings. - The macro expands to anonymous struct of the two string - literals passed as \a sourceText and \a comment. + The macro tells lupdate to collect the string, and expands to an + anonymous struct of the two string literals passed as \a sourceText + and \a disambiguation. Example: diff --git a/src/corelib/global/qglobal.h b/src/corelib/global/qglobal.h index e31d4d9ad7..3684c6b5de 100644 --- a/src/corelib/global/qglobal.h +++ b/src/corelib/global/qglobal.h @@ -1062,7 +1062,7 @@ template static inline typename Wrapper::pointer qGetPtrHelpe #define QT_TRANSLATE_NOOP3(scope, x, comment) {x, comment} #define QT_TRANSLATE_NOOP3_UTF8(scope, x, comment) {x, comment} -#ifndef QT_NO_TRANSLATION // ### This should enclose the NOOPs above +#ifndef QT_NO_TRANSLATION // ### Qt6: This should enclose the NOOPs above // Defined in qcoreapplication.cpp // The better name qTrId() is reserved for an upcoming function which would -- cgit v1.2.3