Doc: Mention that profile storage paths must be set before use

Task-number: QTBUG-66871
Change-Id: I246d667dfe341a6bfe7a74b24286403bec4dde8b
Reviewed-by: Michal Klocek <michal.klocek@qt.io>

2 files changed, 37 insertions, 8 deletions

diff --git a/src/webengine/api/qquickwebengineprofile.cpp b/src/webengine/api/qquickwebengineprofile.cpp
index c89e4d522..dd405f5d7 100644
--- a/src/webengine/api/qquickwebengineprofile.cpp
+++ b/src/webengine/api/qquickwebengineprofile.cpp
@@ -69,11 +69,18 @@ ASSERT_ENUMS_MATCH(QQuickWebEngineDownloadItem::MimeHtmlSaveFormat, QtWebEngineC
 
     \inmodule QtWebEngine
 
-    A web engine profile contains properties and functionality shared by a group of web engine
-    pages.
-
-    Information about visited links is stored together with persistent cookies and other persistent
-    data in a storage described by the persistentStoragePath property.
+    A web engine profile contains settings, scripts, persistent cookie policy, and the list of
+    visited links shared by all web engine pages that belong to the profile.
+
+    Information about visited links is stored together with persistent cookies
+    and other persistent data in a storage determined by the storageName
+    property. Persistent data is stored in a subdirectory determined by the
+    persistentStoragePath property and the cache in a subdirectory determined by
+    the cachePath property. The httpCacheType property describes the type of the
+    cache: \e in-memory or \e on-disk. If only the storageName property is set,
+    the other values are generated automatically based on it. If you specify
+    any of the values manually, you should do it before creating any pages that
+    belong to the profile.
 
     Profiles can be used to isolate pages from each other. A typical use case is a dedicated
     \e {off-the-record profile} for a \e {private browsing} mode. An off-the-record profile forces
@@ -278,8 +285,23 @@ void QQuickWebEngineProfilePrivate::userScripts_clear(QQmlListProperty<QQuickWeb
     \brief Contains settings, scripts, and visited links common to multiple web engine views.
 
     WebEngineProfile contains settings, scripts, and the list of visited links shared by all
-    views that belong to the profile. As such, profiles can be used to isolate views
-    from each other. A typical use case is a dedicated profile for a 'private browsing' mode.
+    views that belong to the profile.
+
+    Information about visited links is stored together with persistent cookies
+    and other persistent data in a storage determined by the storageName
+    property. Persistent data is stored in a subdirectory determined by the
+    persistentStoragePath property and the cache in a subdirectory determined by
+    the cachePath property. The httpCacheType property describes the type of the
+    cache: \e in-memory or \e on-disk. If only the storageName property is set,
+    the other values are generated automatically based on it. If you specify
+    any of the values manually, you should do it before creating any pages that
+    belong to the profile.
+
+    Profiles can be used to isolate pages from each other. A typical use case is
+    a dedicated \e {off-the-record profile} for a \e {private browsing} mode. An
+    off-the-record profile forces cookies, the HTTP cache, and other normally
+    persistent data to be stored only in memory. The offTheRecord property holds
+    whether a profile is off-the-record.
 
     Each web engine view has an associated profile. Views that do not have a specific profile set
     share a common default one.
diff --git a/src/webenginewidgets/api/qwebengineprofile.cpp b/src/webenginewidgets/api/qwebengineprofile.cpp
index 746fe55e8..1885f2085 100644
--- a/src/webenginewidgets/api/qwebengineprofile.cpp
+++ b/src/webenginewidgets/api/qwebengineprofile.cpp
@@ -77,7 +77,14 @@ using QtWebEngineCore::BrowserContextAdapter;
     to a common QWebEngineScriptCollection instance.
 
     Information about visited links is stored together with persistent cookies and other persistent
-    data in a storage returned by persistentStoragePath(). The cache can be cleared of links by
+    data in a storage returned by storageName(). Persistent data is stored in a subdirectory set by
+    calling setPersistentStoragePath(), and the cache is located in a subdirectory set by calling
+    setCachePath(). The cache type can be set to \e in-memory or \e on-disk by calling
+    setHttpCacheType(). If only the storage name is set, the subdirectories are created and named
+    automatically. If you set any of the values manually, you should do it before creating any
+    pages that belong to the profile.
+
+    The cache can be cleared of links by calling
     clearVisitedLinks() or clearAllVisitedLinks(). PersistentCookiesPolicy describes whether
     session and persistent cookies are saved to and restored from memory or disk.