Improve documentation of Document::setPageTextSelection()

Summary:
Improve the documentation of Document::setPageTextSelection()
and PagePrivate::setTextSelections(). Also mention which argument
will be deleted.

Test Plan: Check doxygen output

Reviewers: #okular, aacid

Reviewed By: #okular, aacid

Subscribers: okular-devel

Tags: #okular

Differential Revision: https://phabricator.kde.org/D21069

core/document.h

@@ -582,7 +582,9 @@ class OKULARCORE_EXPORT Document : public QObject
         void removePageAnnotations( int page, const QList<Annotation*> &annotations );
 
         /**
-         * Sets the text selection for the given @p page.
+         * Clears the text selection highlights for the given @p page,
+         * creates new ones if @p rect is not nullptr,
+         * and deletes @p rect.
          *
          * @param page The number of the page.
          * @param rect The rectangle of the selection.

core/page_p.h

@@ -93,7 +93,12 @@ class PagePrivate
         void changeSize( const PageSize &size );
 
         /**
-         * Sets the @p color and @p areas of text selections.
+         * Clears current text selection highlight areas,
+         * creates new ones if @p areas is not nullptr,
+         * and deletes @p areas.
+         *
+         * @param areas Areas of new text selections.
+         * @param color Color of new text selections.
          */
         void setTextSelections( RegularAreaRect *areas, const QColor & color );