diff --git a/.gitignore b/.gitignore
index 53935ba0a39..51779da3ce0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -36,3 +36,8 @@ uv.lock
 .python-version
 
 MODULE.bazel.lock
+
+# Auto-generated by slint-doc-generator
+docs/astro/src/content/collections/enums/
+docs/astro/src/content/collections/structs/
+docs/astro/src/content/docs/reference/global-structs-enums.mdx
diff --git a/docs/astro/src/content/docs/reference/std-widgets/views/listview.mdx b/docs/astro/src/content/docs/reference/std-widgets/views/listview.mdx
index 74967c27e98..e5d1c6c0fbb 100644
--- a/docs/astro/src/content/docs/reference/std-widgets/views/listview.mdx
+++ b/docs/astro/src/content/docs/reference/std-widgets/views/listview.mdx
@@ -6,9 +6,12 @@ description: ListView api.
 import CodeSnippetMD from '@slint/common-files/src/components/CodeSnippetMD.astro';
 import Link from '@slint/common-files/src/components/Link.astro';
 
-A ListView is like a Scrollview but it should have a `for` element, and the content are
+A ListView is like a <Link type="ScrollView"/> but it should have a `for` element, and the contents are
 automatically laid out in a list.
-Elements are only instantiated if they are visible
+
+In a ListView, elements are only instantiated if they are visible, which guarantees stable performance with a practically unlimited number of items.
+For this reason, prefer ListView to display long lists of items.
+<Link type="ScrollView"/> is more suitable for a small number of items or for free-form content.
 
 <CodeSnippetMD imagePath="/src/assets/generated/std-widgets-listview-example.png"  imageWidth="200" imageHeight="200"  imageAlt='listview example'>
 ```slint playground
diff --git a/docs/astro/src/content/docs/reference/std-widgets/views/scrollview.mdx b/docs/astro/src/content/docs/reference/std-widgets/views/scrollview.mdx
index 990b2575b7a..0721405a93c 100644
--- a/docs/astro/src/content/docs/reference/std-widgets/views/scrollview.mdx
+++ b/docs/astro/src/content/docs/reference/std-widgets/views/scrollview.mdx
@@ -5,6 +5,7 @@ description: ScrollView api.
 
 import SlintProperty from '@slint/common-files/src/components/SlintProperty.astro';
 import CodeSnippetMD from '@slint/common-files/src/components/CodeSnippetMD.astro';
+import Link from '@slint/common-files/src/components/Link.astro';
 
 <CodeSnippetMD imagePath="/src/assets/generated/std-widgets-scrollview.png"  imageWidth="200" imageHeight="200"  imageAlt='scrollview example'>
 ```slint playground
@@ -27,7 +28,7 @@ export component Example inherits Window {
 </CodeSnippetMD>
 
 A Scrollview contains a viewport that is bigger than the view and can be
-scrolled. It has scrollbar to interact with.
+scrolled. Compared to a plain <Link type="Flickable"/> it has scrollbar to interact with.
 
 The ScrollView is scrollable if the `viewport-width` and `viewport-height` properties
 are bigger than the size of the visible area.
@@ -35,6 +36,11 @@ are bigger than the size of the visible area.
 If the ScrollView contains a layout, the default value for the `viewport-width` and
 `viewport-height` is the minimum size of that layout.
 
+:::note{Note}
+A ScrollView will always instantiate all of its children, so its performance may degrade with large number of children, even if they are not visible.
+If you want to display a long list of items, use a <Link type="ListView"/> instead, which only instantiates visible children.
+:::
+
 ## Properties
 
 ### enabled
diff --git a/internal/compiler/builtins.slint b/internal/compiler/builtins.slint
index 58c22e988ff..2a9ab5f7893 100644
--- a/internal/compiler/builtins.slint
+++ b/internal/compiler/builtins.slint
@@ -923,19 +923,22 @@ component KeyBinding {
 /// ```
 ///
 /// The `Flickable` is a low-level element that is the base for scrollable
-/// widgets, such as the <Link type="ScrollView"/>. When the `viewport-width` or the
-/// `viewport-height` is greater than the parent's `width` or `height`
-/// respectively, the element becomes scrollable. Note that the `Flickable`
-/// doesn't create a scrollbar. When unset, the `viewport-width` and `viewport-height` are
+/// widgets, such as the <Link type="ScrollView"/> or <Link type="ListView"/>.
+/// When the `viewport-width` or the `viewport-height` is greater than the parent's `width` or `height`
+/// respectively, the element becomes scrollable.
+///
+/// When unset, the `viewport-width` and `viewport-height` are
 /// calculated automatically based on the `Flickable`'s children. This isn't the
 /// case when using a `for` loop to populate the elements. This is a bug tracked in
 /// issue [#407](https://github.com/slint-ui/slint/issues/407).
 /// The maximum and preferred size of the `Flickable` are based on the viewport.
 ///
+/// Note that the `Flickable` doesn't create a scrollbar.
+/// You can use a <Link type="ScrollView"/> instead or add your own scroll bars.
+///
 /// When not part of a layout, its width or height defaults to 100% of the parent
 /// element when not specified.
 ///
-///
 /// ## Pointer Event Interaction
 ///
 /// If the `Flickable`'s area contains elements that use `TouchArea` to act on clicking, such as `Button`