Text and TextEdit: document MarkdownText format

Task-number: QTBUG-81306
Change-Id: I8ee50727f4e75eee8c0997f17193d8c99e855551
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

5 files changed, 209 insertions, 62 deletions

diff --git a/src/quick/doc/images/declarative-textformat.png b/src/quick/doc/images/declarative-textformat.png
index ade1b45429..a671fbf3d6 100644
--- a/src/quick/doc/images/declarative-textformat.png
+++ b/src/quick/doc/images/declarative-textformat.png
diff --git a/src/quick/doc/snippets/qml/text/textEditFormats.qml b/src/quick/doc/snippets/qml/text/textEditFormats.qml
new file mode 100644
index 0000000000..9065cc6a1c
--- /dev/null
+++ b/src/quick/doc/snippets/qml/text/textEditFormats.qml
@@ -0,0 +1,76 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtQuick module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+import QtQuick 2.14
+
+//![0]
+Column {
+    TextEdit {
+        font.pointSize: 24
+        textFormat: TextEdit.AutoText
+        text: "<b>Hello</b> <i>World!</i>"
+    }
+    TextEdit {
+        font.pointSize: 24
+        textFormat: TextEdit.RichText
+        text: "<b>Hello</b> <i>World!</i>"
+    }
+    TextEdit {
+        font.pointSize: 24
+        textFormat: TextEdit.PlainText
+        text: "<b>Hello</b> <i>World!</i>"
+    }
+    TextEdit {
+        font.pointSize: 24
+        textFormat: TextEdit.MarkdownText
+        text: "**Hello** *World!*"
+    }
+}
+//![0]
+
diff --git a/src/quick/doc/snippets/qml/text/textFormats.qml b/src/quick/doc/snippets/qml/text/textFormats.qml
new file mode 100644
index 0000000000..b292a3ee13
--- /dev/null
+++ b/src/quick/doc/snippets/qml/text/textFormats.qml
@@ -0,0 +1,75 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtQuick module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+import QtQuick 2.14
+
+//![0]
+Column {
+    Text {
+        font.pointSize: 24
+        text: "<b>Hello</b> <i>World!</i>"
+    }
+    Text {
+        font.pointSize: 24
+        textFormat: Text.RichText
+        text: "<b>Hello</b> <i>World!</i>"
+    }
+    Text {
+        font.pointSize: 24
+        textFormat: Text.PlainText
+        text: "<b>Hello</b> <i>World!</i>"
+    }
+    Text {
+        font.pointSize: 24
+        textFormat: Text.MarkdownText
+        text: "**Hello** *World!*"
+    }
+}
+//![0]
+
diff --git a/src/quick/items/qquicktext.cpp b/src/quick/items/qquicktext.cpp
index ae849aeb4b..b95a2559ff 100644
--- a/src/quick/items/qquicktext.cpp
+++ b/src/quick/items/qquicktext.cpp
@@ -1640,6 +1640,9 @@ void QQuickText::itemChange(ItemChange change, const ItemChangeData &value)
 
     The item will try to automatically determine whether the text should
     be treated as styled text. This determination is made using Qt::mightBeRichText().
+    However, detection of Markdown is not automatic.
+
+    \sa textFormat
 */
 QString QQuickText::text() const
 {
@@ -2067,26 +2070,25 @@ void QQuickText::resetMaximumLineCount()
 /*!
     \qmlproperty enumeration QtQuick::Text::textFormat
 
-    The way the text property should be displayed.
+    The way the \l text property should be displayed.
 
     Supported text formats are:
 
-    \list
-    \li Text.AutoText (default)
-    \li Text.PlainText
-    \li Text.StyledText
-    \li Text.RichText
-    \endlist
+    \value Text.AutoText        (default) detected via the Qt::mightBeRichText() heuristic
+    \value Text.PlainText       all styling tags are treated as plain text
+    \value Text.StyledText      optimized basic rich text as in HTML 3.2
+    \value Text.RichText        \l {Supported HTML Subset} {a subset of HTML 4}
+    \value Text.MarkdownText    \l {https://commonmark.org/help/}{CommonMark} plus the
+                                \l {https://guides.github.com/features/mastering-markdown/}{GitHub}
+                                extensions for tables and task lists (since 5.14)
 
     If the text format is \c Text.AutoText the Text item
     will automatically determine whether the text should be treated as
-    styled text.  This determination is made using Qt::mightBeRichText()
-    which uses a fast and therefore simple heuristic. It mainly checks
-    whether there is something that looks like a tag before the first
-    line break. Although the result may be correct for common cases,
-    there is no guarantee.
+    styled text.  This determination is made using Qt::mightBeRichText(),
+    which can detect the presence of an HTML tag on the first line of text,
+    but cannot distinguish Markdown from plain text.
 
-    Text.StyledText is an optimized format supporting some basic text
+    \c Text.StyledText is an optimized format supporting some basic text
     styling markup, in the style of HTML 3.2:
 
     \code
@@ -2112,30 +2114,21 @@ void QQuickText::resetMaximumLineCount()
     \table
     \row
     \li
-    \qml
-Column {
-    Text {
-        font.pointSize: 24
-        text: "<b>Hello</b> <i>World!</i>"
-    }
-    Text {
-        font.pointSize: 24
-        textFormat: Text.RichText
-        text: "<b>Hello</b> <i>World!</i>"
-    }
-    Text {
-        font.pointSize: 24
-        textFormat: Text.PlainText
-        text: "<b>Hello</b> <i>World!</i>"
-    }
-}
-    \endqml
+    \snippet qml/text/textFormats.qml 0
     \li \image declarative-textformat.png
     \endtable
 
-    Text.RichText supports a larger subset of HTML 4, as described on the
-    \l {Supported HTML Subset} page. You should prefer using Text.PlainText
-    or Text.StyledText instead, as they offer better performance.
+    \c Text.RichText supports a larger subset of HTML 4, as described on the
+    \l {Supported HTML Subset} page. You should prefer using \c Text.PlainText,
+    \c Text.StyledText or \c Text.MarkdownText instead, as they offer better performance.
+
+    \note With \c Text.MarkdownText, and with the supported subset of HTML,
+    some decorative elements are not rendered as they would be in a web browser:
+    \list
+    \li code blocks use the \l {QFontDatabase::FixedFont}{default monospace font} but without a surrounding highlight box
+    \li block quotes are indented, but there is no vertical line alongside the quote
+    \li horizontal rules are not rendered
+    \endlist
 */
 QQuickText::TextFormat QQuickText::textFormat() const
 {
diff --git a/src/quick/items/qquicktextedit.cpp b/src/quick/items/qquicktextedit.cpp
index 7d34cc3f56..650b1961a4 100644
--- a/src/quick/items/qquicktextedit.cpp
+++ b/src/quick/items/qquicktextedit.cpp
@@ -395,6 +395,7 @@ QString QQuickTextEdit::text() const
     The text to display.  If the text format is AutoText the text edit will
     automatically determine whether the text should be treated as
     rich text.  This determination is made using Qt::mightBeRichText().
+    However, detection of Markdown is not automatic.
 
     The text-property is mostly suitable for setting the initial content and
     handling modifications to relatively small text content. The append(),
@@ -402,7 +403,7 @@ QString QQuickTextEdit::text() const
     remarkably better performance for modifying especially large rich text
     content.
 
-    \sa clear()
+    \sa clear(), textFormat
 */
 void QQuickTextEdit::setText(const QString &text)
 {
@@ -444,41 +445,43 @@ QString QQuickTextEdit::preeditText() const
 /*!
     \qmlproperty enumeration QtQuick::TextEdit::textFormat
 
-    The way the text property should be displayed.
+    The way the \l text property should be displayed.
 
-    \list
-    \li TextEdit.AutoText
-    \li TextEdit.PlainText
-    \li TextEdit.RichText
-    \endlist
+    Supported text formats are:
 
-    The default is TextEdit.PlainText.  If the text format is TextEdit.AutoText the text edit
-    will automatically determine whether the text should be treated as
-    rich text.  This determination is made using Qt::mightBeRichText().
+    \value TextEdit.PlainText       (default) all styling tags are treated as plain text
+    \value TextEdit.AutoText        detected via the Qt::mightBeRichText() heuristic
+    \value TextEdit.RichText        \l {Supported HTML Subset} {a subset of HTML 4}
+    \value TextEdit.MarkdownText    \l {https://commonmark.org/help/}{CommonMark} plus the
+                                    \l {https://guides.github.com/features/mastering-markdown/}{GitHub}
+                                    extensions for tables and task lists (since 5.14)
+
+    The default is \c TextEdit.PlainText. If the text format is set to
+    \c TextEdit.AutoText, the text edit will automatically determine whether
+    the text should be treated as rich text. This determination is made using
+    Qt::mightBeRichText(), which can detect the presence of an HTML tag on the
+    first line of text, but cannot distinguish Markdown from plain text.
 
     \table
     \row
     \li
-    \qml
-Column {
-    TextEdit {
-        font.pointSize: 24
-        text: "<b>Hello</b> <i>World!</i>"
-    }
-    TextEdit {
-        font.pointSize: 24
-        textFormat: TextEdit.RichText
-        text: "<b>Hello</b> <i>World!</i>"
-    }
-    TextEdit {
-        font.pointSize: 24
-        textFormat: TextEdit.PlainText
-        text: "<b>Hello</b> <i>World!</i>"
-    }
-}
-    \endqml
+    \snippet qml/text/textEditFormats.qml 0
     \li \image declarative-textformat.png
     \endtable
+
+    With \c TextEdit.MarkdownText, checkboxes that result from using the
+    \l {https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown}{GitHub checkbox extension}
+    are interactively checkable.
+
+    \note Interactively typing markup or markdown formatting is not supported.
+
+    \note With \c Text.MarkdownText, and with the supported subset of HTML,
+    some decorative elements are not rendered as they would be in a web browser:
+    \list
+    \li code blocks use the \l {QFontDatabase::FixedFont}{default monospace font} but without a surrounding highlight box
+    \li block quotes are indented, but there is no vertical line alongside the quote
+    \li horizontal rules are not rendered
+    \endlist
 */
 QQuickTextEdit::TextFormat QQuickTextEdit::textFormat() const
 {