doc: Add QTextDocument::MarkdownFeature docs

Detailed docs were omitted before (and QTextMarkdownImporter::Feature is
not public) because
- "GitHub dialect" is a moving target (although we may have supported
  all known features when it was introduced). We should reserve the
  right to add to the feature set accordingly: so the numeric flags
  can be expected to change.
- the writer mostly ignores the feature flags and writes back to
  GitHub dialect; only the front matter can be omitted that way
- recognizing non-URL links seems fuzzy; md4c does it, so we allow that
  feature, but if it goes wrong it would be an md4c bug
- hex flags look strange: in fact they come from
  https://github.com/mity/md4c/blob/master/src/md4c.h#L306
  If we assume that they might change, it would be better not to
  document the numeric values in detail. But so far, md4c has never
  removed any, only added a few (and we don't yet support all the
  new ones).

Change-Id: I6552da1226bf7ad6242432c1d5d3df9ec8f61d6f
Pick-to: 6.9
Reviewed-by: David Boddie <david.boddie@qt.io>
Reviewed-by: Tommi M. Tauriainen <tommi.m.tauriainen@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

src/gui/text/qtextdocument.cpp

@@ -3689,6 +3689,45 @@ QString QTextDocument::toMarkdown(QTextDocument::MarkdownFeatures features) cons
 }
 #endif
 
+/*!
+    \since 5.14
+    \enum QTextDocument::MarkdownFeature
+
+    This enum selects the supported feature set when reading or writing Markdown.
+
+    \value MarkdownNoHTML
+        Any HTML tags in the Markdown text will be discarded
+    \value MarkdownDialectCommonMark
+        Only the features standardized by \l {https://spec.commonmark.org/0.31.2/}{CommonMark}
+    \value MarkdownDialectGitHub
+        Most features from the
+        \l {https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax}
+        {GitHub dialect}
+
+    Specifically, the supported subset of the GitHub dialect includes
+    everything from CommonMark, plus:
+
+    \list
+    \li recognizing URLs, www and email addresses and turning them into links
+    \li strikethrough
+    \li underline (distinct from italics; in CommonMark it's the same)
+    \li tables
+    \li task lists
+    \li \l {QTextDocument::metaInformation()}{front matter}
+    \endlist
+
+    "Front matter" is often metadata in YAML format. Qt does not currently
+    include a parser for that; but you may choose a third-party parser, call
+    QTextDocument::metaInformation() to get the whole block, and invoke your
+    own parser after Qt has parsed the Markdown file.
+
+    \note The Markdown output from toMarkdown() currently may include GitHub
+    features even if you attempt to disable them by specifying another enum
+    value. This may be fixed in a future version of Qt.
+
+    \sa toMarkdown(), setMarkdown()
+*/
+
 /*!
     \since 5.14
     Replaces the entire contents of the document with the given
@@ -3706,16 +3745,7 @@ QString QTextDocument::toMarkdown(QTextDocument::MarkdownFeatures features) cons
     not supported.
 
     Some features of the parser can be enabled or disabled via the \a features
-    argument:
+    argument. The default is \c MarkdownDialectGitHub.
-
-    \value MarkdownNoHTML
-           Any HTML tags in the Markdown text will be discarded
-    \value MarkdownDialectCommonMark
-           The parser supports only the features standardized by CommonMark
-    \value MarkdownDialectGitHub
-           The parser supports the GitHub dialect
-
-    The default is \c MarkdownDialectGitHub.
 
     The undo/redo history is reset when this function is called.
 */