doc: Add docs for PdfScrollablePageView and PdfPageView

Task-number: QTBUG-81560
Change-Id: Ib91da92942311f65e3a2a40eb08c5a7f053419b4
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>
(cherry picked from commit 533b8f6d0c9bdd7f9b4eec6db5b37202247edd66)

2 files changed, 433 insertions, 6 deletions

diff --git a/src/pdfquick/qml/PdfPageView.qml b/src/pdfquick/qml/PdfPageView.qml
index 986f4156e..28789002c 100644
--- a/src/pdfquick/qml/PdfPageView.qml
+++ b/src/pdfquick/qml/PdfPageView.qml
@@ -42,36 +42,187 @@ import QtQuick.Pdf 5.15
 import QtQuick.Shapes 1.14
 import Qt.labs.animation 1.0
 
+/*!
+    \qmltype PdfPageView
+    \inqmlmodule QtQuick.Pdf
+    \brief A PDF viewer component to show one page a time.
+
+    PdfPageView provides a PDF viewer component that shows one whole page at a
+    time, without scrolling. It supports selecting text and copying it to the
+    clipboard, zooming in and out, clicking an internal link to jump to another
+    section in the document, rotating the view, and searching for text.
+
+    The implementation is a QML assembly of smaller building blocks that are
+    available separately. In case you want to make changes in your own version
+    of this component, you can copy the QML, which is installed into the
+    \c QtQuick/Pdf/qml module directory, and modify it as needed.
+
+    \sa PdfScrollablePageView, PdfMultiPageView, PdfStyle
+*/
 Rectangle {
-    // public API
-    // TODO 5.15: required property
-    property var document: undefined
+    /*!
+        \qmlproperty PdfDocument PdfPageView::document
+
+        A PdfDocument object with a valid \c source URL is required:
+
+        \snippet multipageview.qml 0
+    */
+    required property PdfDocument document
+
+    /*!
+        \qmlproperty int PdfPageView::status
+
+        This property holds the \l {QtQuick::Image::status}{rendering status} of
+        the \l {currentPage}{current page}.
+
+        \sa PdfPageImage::status
+    */
     property alias status: image.status
 
+    /*!
+        \qmlproperty PdfDocument PdfPageView::selectedText
+
+        The selected text.
+    */
     property alias selectedText: selection.text
+
+    /*!
+        \qmlmethod void PdfPageView::selectAll()
+
+        Selects all the text on the \l {currentPage}{current page}, and makes it
+        available as the system \l {QClipboard::Selection}{selection} on systems
+        that support that feature.
+
+        \sa copySelectionToClipboard()
+    */
     function selectAll() {
         selection.selectAll()
     }
+
+    /*!
+        \qmlmethod void PdfPageView::copySelectionToClipboard()
+
+        Copies the selected text (if any) to the
+        \l {QClipboard::Clipboard}{system clipboard}.
+
+        \sa selectAll()
+    */
     function copySelectionToClipboard() {
         selection.copyToClipboard()
     }
 
+    // --------------------------------
     // page navigation
+
+    /*!
+        \qmlproperty int PdfPageView::currentPage
+        \readonly
+
+        This property holds the zero-based page number of the page visible in the
+        scrollable view. If there is no current page, it holds -1.
+
+        This property is read-only, and is typically used in a binding (or
+        \c onCurrentPageChanged script) to update the part of the user interface
+        that shows the current page number, such as a \l SpinBox.
+
+        \sa PdfNavigationStack::currentPage
+    */
     property alias currentPage: navigationStack.currentPage
+
+    /*!
+        \qmlproperty bool PdfPageView::backEnabled
+        \readonly
+
+        This property indicates if it is possible to go back in the navigation
+        history to a previous-viewed page.
+
+        \sa PdfNavigationStack::backAvailable, back()
+    */
     property alias backEnabled: navigationStack.backAvailable
+
+    /*!
+        \qmlproperty bool PdfPageView::forwardEnabled
+        \readonly
+
+        This property indicates if it is possible to go to next location in the
+        navigation history.
+
+        \sa PdfNavigationStack::forwardAvailable, forward()
+    */
     property alias forwardEnabled: navigationStack.forwardAvailable
+
+    /*!
+        \qmlmethod void PdfPageView::back()
+
+        Scrolls the view back to the previous page that the user visited most
+        recently; or does nothing if there is no previous location on the
+        navigation stack.
+
+        \sa PdfNavigationStack::back(), currentPage, backEnabled
+    */
     function back() { navigationStack.back() }
+
+    /*!
+        \qmlmethod void PdfPageView::forward()
+
+        Scrolls the view to the page that the user was viewing when the back()
+        method was called; or does nothing if there is no "next" location on the
+        navigation stack.
+
+        \sa PdfNavigationStack::forward(), currentPage
+    */
     function forward() { navigationStack.forward() }
+
+    /*!
+        \qmlmethod void PdfPageView::goToPage(int page)
+
+        Changes the view to the \a page, if possible.
+
+        \sa PdfNavigationStack::jump(), currentPage
+    */
     function goToPage(page) { goToLocation(page, Qt.point(0, 0), 0) }
+
+    /*!
+        \qmlmethod void PdfPageView::goToLocation(int page, point location, real zoom)
+
+        Scrolls the view to the \a location on the \a page, if possible,
+        and sets the \a zoom level.
+
+        \sa PdfNavigationStack::jump(), currentPage
+    */
     function goToLocation(page, location, zoom) {
         if (zoom > 0)
             root.renderScale = zoom
         navigationStack.push(page, location, zoom)
     }
 
+    // --------------------------------
     // page scaling
+
+    /*!
+        \qmlproperty real PdfPageView::renderScale
+
+        This property holds the ratio of pixels to points. The default is \c 1,
+        meaning one point (1/72 of an inch) equals 1 logical pixel.
+
+        \sa PdfPageImage::status
+    */
     property real renderScale: 1
+
+    /*!
+        \qmlproperty size PdfPageView::sourceSize
+
+        This property holds the scaled width and height of the full-frame image.
+
+        \sa PdfPageImage::sourceSize
+    */
     property alias sourceSize: image.sourceSize
+
+    /*!
+        \qmlmethod void PdfPageView::resetScale()
+
+        Sets \l renderScale back to its default value of \c 1.
+    */
     function resetScale() {
         image.sourceSize.width = 0
         image.sourceSize.height = 0
@@ -79,6 +230,15 @@ Rectangle {
         root.y = 0
         root.scale = 1
     }
+
+    /*!
+        \qmlmethod void PdfPageView::scaleToWidth(real width, real height)
+
+        Sets \l renderScale such that the width of the first page will fit into a
+        viewport with the given \a width and \a height. If the page is not rotated,
+        it will be scaled so that its width fits \a width. If it is rotated +/- 90
+        degrees, it will be scaled so that its width fits \a height.
+    */
     function scaleToWidth(width, height) {
         var halfRotation = Math.abs(root.rotation % 180)
         image.sourceSize = Qt.size((halfRotation > 45 && halfRotation < 135) ? height : width, 0)
@@ -89,6 +249,15 @@ Rectangle {
         image.vCenterOnLoad = (halfRotation > 45 && halfRotation < 135)
         root.scale = 1
     }
+
+    /*!
+        \qmlmethod void PdfPageView::scaleToPage(real width, real height)
+
+        Sets \l renderScale such that the whole first page will fit into a viewport
+        with the given \a width and \a height. The resulting \l renderScale depends
+        on \l pageRotation: the page will fit into the viewport at a larger size if
+        it is first rotated to have a matching aspect ratio.
+    */
     function scaleToPage(width, height) {
         var windowAspect = width / height
         var halfRotation = Math.abs(root.rotation % 180)
@@ -115,12 +284,49 @@ Rectangle {
         root.scale = 1
     }
 
+    // --------------------------------
     // text search
+
+    /*!
+        \qmlproperty PdfSearchModel PdfPageView::searchModel
+
+        This property holds a PdfSearchModel containing the list of search results
+        for a given \l searchString.
+
+        \sa PdfSearchModel
+    */
     property alias searchModel: searchModel
+
+    /*!
+        \qmlproperty string PdfPageView::searchString
+
+        This property holds the search string that the user may choose to search
+        for. It is typically used in a binding to the
+        \l {QtQuick.Controls::TextField::text}{text} property of a TextField.
+
+        \sa searchModel
+    */
     property alias searchString: searchModel.searchString
+
+    /*!
+        \qmlmethod void PdfPageView::searchBack()
+
+        Decrements the
+        \l{PdfSearchModel::currentResult}{searchModel's current result}
+        so that the view will jump to the previous search result.
+    */
     function searchBack() { --searchModel.currentResult }
+
+    /*!
+        \qmlmethod void PdfPageView::searchForward()
+
+        Increments the
+        \l{PdfSearchModel::currentResult}{searchModel's current result}
+        so that the view will jump to the next search result.
+    */
     function searchForward() { ++searchModel.currentResult }
 
+    // --------------------------------
     // implementation
     id: root
     width: image.width
diff --git a/src/pdfquick/qml/PdfScrollablePageView.qml b/src/pdfquick/qml/PdfScrollablePageView.qml
index 4c8db84b8..6cbb4bc2d 100644
--- a/src/pdfquick/qml/PdfScrollablePageView.qml
+++ b/src/pdfquick/qml/PdfScrollablePageView.qml
@@ -42,46 +42,221 @@ import QtQuick.Pdf 5.15
 import QtQuick.Shapes 1.14
 import Qt.labs.animation 1.0
 
+/*!
+    \qmltype PdfScrollablePageView
+    \inqmlmodule QtQuick.Pdf
+    \brief A complete PDF viewer component to show one page a time, with scrolling.
+
+    PdfScrollablePageView provides a PDF viewer component that shows one page
+    at a time, with scrollbars to move around the page. It also supports
+    selecting text and copying it to the clipboard, zooming in and out,
+    clicking an internal link to jump to another section in the document,
+    rotating the view, and searching for text. The pdfviewer example
+    demonstrates how to use these features in an application.
+
+    The implementation is a QML assembly of smaller building blocks that are
+    available separately. In case you want to make changes in your own version
+    of this component, you can copy the QML, which is installed into the
+    \c QtQuick/Pdf/qml module directory, and modify it as needed.
+
+    \sa PdfPageView, PdfMultiPageView, PdfStyle
+*/
 Flickable {
-    // public API
-    // TODO 5.15: required property
-    property var document: undefined
     property bool debug: false
+    // public API
+
+    /*!
+        \qmlproperty PdfDocument PdfScrollablePageView::document
+
+        A PdfDocument object with a valid \c source URL is required:
+
+        \snippet multipageview.qml 0
+    */
+    required property PdfDocument document
+
+    /*!
+        \qmlproperty int PdfScrollablePageView::status
+
+        This property holds the \l {QtQuick::Image::status}{rendering status} of
+        the \l {currentPage}{current page}.
+
+        \sa PdfPageImage::status
+    */
     property alias status: image.status
 
+    /*!
+        \qmlproperty PdfDocument PdfScrollablePageView::selectedText
+
+        The selected text.
+    */
     property alias selectedText: selection.text
+
+    /*!
+        \qmlmethod void PdfScrollablePageView::selectAll()
+
+        Selects all the text on the \l {currentPage}{current page}, and makes it
+        available as the system \l {QClipboard::Selection}{selection} on systems
+        that support that feature.
+
+        \sa copySelectionToClipboard()
+    */
     function selectAll() {
         selection.selectAll()
     }
+
+    /*!
+        \qmlmethod void PdfScrollablePageView::copySelectionToClipboard()
+
+        Copies the selected text (if any) to the
+        \l {QClipboard::Clipboard}{system clipboard}.
+
+        \sa selectAll()
+    */
     function copySelectionToClipboard() {
         selection.copyToClipboard()
     }
 
+    // --------------------------------
     // page navigation
+
+    /*!
+        \qmlproperty int PdfScrollablePageView::currentPage
+        \readonly
+
+        This property holds the zero-based page number of the page visible in the
+        scrollable view. If there is no current page, it holds -1.
+
+        This property is read-only, and is typically used in a binding (or
+        \c onCurrentPageChanged script) to update the part of the user interface
+        that shows the current page number, such as a \l SpinBox.
+
+        \sa PdfNavigationStack::currentPage
+    */
     property alias currentPage: navigationStack.currentPage
+
+    /*!
+        \qmlproperty bool PdfScrollablePageView::backEnabled
+        \readonly
+
+        This property indicates if it is possible to go back in the navigation
+        history to a previous-viewed page.
+
+        \sa PdfNavigationStack::backAvailable, back()
+    */
     property alias backEnabled: navigationStack.backAvailable
+
+    /*!
+        \qmlproperty bool PdfScrollablePageView::forwardEnabled
+        \readonly
+
+        This property indicates if it is possible to go to next location in the
+        navigation history.
+
+        \sa PdfNavigationStack::forwardAvailable, forward()
+    */
     property alias forwardEnabled: navigationStack.forwardAvailable
+
+    /*!
+        \qmlmethod void PdfScrollablePageView::back()
+
+        Scrolls the view back to the previous page that the user visited most
+        recently; or does nothing if there is no previous location on the
+        navigation stack.
+
+        \sa PdfNavigationStack::back(), currentPage, backEnabled
+    */
     function back() { navigationStack.back() }
+
+    /*!
+        \qmlmethod void PdfScrollablePageView::forward()
+
+        Scrolls the view to the page that the user was viewing when the back()
+        method was called; or does nothing if there is no "next" location on the
+        navigation stack.
+
+        \sa PdfNavigationStack::forward(), currentPage
+    */
     function forward() { navigationStack.forward() }
+
+    /*!
+        \qmlmethod void PdfScrollablePageView::goToPage(int page)
+
+        Changes the view to the \a page, if possible.
+
+        \sa PdfNavigationStack::jump(), currentPage
+    */
     function goToPage(page) {
         if (page === navigationStack.currentPage)
             return
         goToLocation(page, Qt.point(0, 0), 0)
     }
+
+    /*!
+        \qmlmethod void PdfScrollablePageView::goToLocation(int page, point location, real zoom)
+
+        Scrolls the view to the \a location on the \a page, if possible,
+        and sets the \a zoom level.
+
+        \sa PdfNavigationStack::jump(), currentPage
+    */
     function goToLocation(page, location, zoom) {
         if (zoom > 0)
             root.renderScale = zoom
         navigationStack.push(page, location, zoom)
     }
 
+    // --------------------------------
     // page scaling
+
+    /*!
+        \qmlproperty real PdfScrollablePageView::renderScale
+
+        This property holds the ratio of pixels to points. The default is \c 1,
+        meaning one point (1/72 of an inch) equals 1 logical pixel.
+
+        \sa PdfPageImage::status
+    */
     property real renderScale: 1
+
+    /*!
+        \qmlproperty real PdfScrollablePageView::pageRotation
+
+        This property holds the clockwise rotation of the pages.
+
+        The default value is \c 0 degrees (that is, no rotation relative to the
+        orientation of the pages as stored in the PDF file).
+
+        \sa PdfPageImage::rotation
+    */
     property real pageRotation: 0
+
+    /*!
+        \qmlproperty size PdfScrollablePageView::sourceSize
+
+        This property holds the scaled width and height of the full-frame image.
+
+        \sa PdfPageImage::sourceSize
+    */
     property alias sourceSize: image.sourceSize
+
+    /*!
+        \qmlmethod void PdfScrollablePageView::resetScale()
+
+        Sets \l renderScale back to its default value of \c 1.
+    */
     function resetScale() {
         paper.scale = 1
         root.renderScale = 1
     }
+
+    /*!
+        \qmlmethod void PdfScrollablePageView::scaleToWidth(real width, real height)
+
+        Sets \l renderScale such that the width of the first page will fit into a
+        viewport with the given \a width and \a height. If the page is not rotated,
+        it will be scaled so that its width fits \a width. If it is rotated +/- 90
+        degrees, it will be scaled so that its width fits \a height.
+    */
     function scaleToWidth(width, height) {
         var pagePointSize = document.pagePointSize(navigationStack.currentPage)
         root.renderScale = root.width / (paper.rot90 ? pagePointSize.height : pagePointSize.width)
@@ -90,6 +265,15 @@ Flickable {
         root.contentX = 0
         root.contentY = 0
     }
+
+    /*!
+        \qmlmethod void PdfScrollablePageView::scaleToPage(real width, real height)
+
+        Sets \l renderScale such that the whole first page will fit into a viewport
+        with the given \a width and \a height. The resulting \l renderScale depends
+        on \l pageRotation: the page will fit into the viewport at a larger size if
+        it is first rotated to have a matching aspect ratio.
+    */
     function scaleToPage(width, height) {
         var pagePointSize = document.pagePointSize(navigationStack.currentPage)
         root.renderScale = Math.min(
@@ -99,12 +283,49 @@ Flickable {
         root.contentY = 0
     }
 
+    // --------------------------------
     // text search
+
+    /*!
+        \qmlproperty PdfSearchModel PdfScrollablePageView::searchModel
+
+        This property holds a PdfSearchModel containing the list of search results
+        for a given \l searchString.
+
+        \sa PdfSearchModel
+    */
     property alias searchModel: searchModel
+
+    /*!
+        \qmlproperty string PdfScrollablePageView::searchString
+
+        This property holds the search string that the user may choose to search
+        for. It is typically used in a binding to the
+        \l {QtQuick.Controls::TextField::text}{text} property of a TextField.
+
+        \sa searchModel
+    */
     property alias searchString: searchModel.searchString
+
+    /*!
+        \qmlmethod void PdfScrollablePageView::searchBack()
+
+        Decrements the
+        \l{PdfSearchModel::currentResult}{searchModel's current result}
+        so that the view will jump to the previous search result.
+    */
     function searchBack() { --searchModel.currentResult }
+
+    /*!
+        \qmlmethod void PdfScrollablePageView::searchForward()
+
+        Increments the
+        \l{PdfSearchModel::currentResult}{searchModel's current result}
+        so that the view will jump to the next search result.
+    */
     function searchForward() { ++searchModel.currentResult }
 
+    // --------------------------------
     // implementation
     id: root
     PdfStyle { id: style }