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>

1 files changed, 31 insertions, 28 deletions

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
 {