diff --git a/core/document.h b/core/document.h
--- a/core/document.h
+++ b/core/document.h
@@ -582,7 +582,9 @@
         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.
diff --git a/core/page_p.h b/core/page_p.h
--- a/core/page_p.h
+++ b/core/page_p.h
@@ -93,7 +93,12 @@
         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 );