Some changes to the migration docs

Fixes #888

CHANGELOG.md

@@ -4,7 +4,8 @@ All notable changes to this project will be documented in this file.
 ## Unreleased
 
 This version changes some APIs in incompatible ways. For details how to migrate your application code, see the [C++ migration guide](api/sixtyfps-cpp/docs/cpp_migration.md)
-as well as the [Rust migration guide](api/sixtyfps-rs/migration.md).
+as well as the [Rust migration guide for the `sixtyfps` crate](api/sixtyfps-rs/migration.md) and for the
+[`sixtyfps-interpreter` crate](sixtyfps_runtime/interpreter/migration.rs).
 
 ### Changed
 

api/sixtyfps-rs/docs.rs

@@ -164,3 +164,8 @@ pub mod debugging_techniques {
     #![doc = include_str!("docs/debugging_techniques.md")]
     #![doc = ""]
 }
+
+pub mod migration {
+    #![doc = include_str!("migration.md")]
+    use crate::*;
+}

api/sixtyfps-rs/lib.rs

@@ -17,6 +17,7 @@ If you are already familiar with SixtyFPS, the following topics provide some
  * [Widgets](docs::widgets)
  * [Positioning and Layout of Elements](docs::layouting)
  * [Debugging Techniques](docs::debugging_techniques)
+ * [Migration from older version](docs::migration)
 
 ## How to use this crate:
 

api/sixtyfps-rs/migration.md

@@ -12,9 +12,12 @@ In 0.2.0 we have increased the minimum version of rust. You need to have rust co
 
 #### `Model::row_data`
 
-`Model::row_data` now returns an `Option<T>` instead of a simple `T`.
+[`Model::row_data`] now returns an `Option<T>` instead of a simple `T`.
 
-This implies that `Model`s must handle invalid indices and may not panic when they encounter one.
+[`Model`] implementation must no longer panic when encountering invalid index in [`row_data`](Model::row_data)
+and [`set_row_data`](Model::set_row_data), they should return `None` instead.
+
+When calling `row_data` one need to unwrap the value
 
 Old code:
 
@@ -30,11 +33,14 @@ let row_five = model.row_data(5).unwrap_or_default();
 
 #### `Model::attach_peer` and `Model::model_tracker`
 
-`attach_peer()` has been removed. Instead you must implement the `fn model_tracker(&self) -> &dyn ModelTracker` function. If you have a constant model, then you can just return `&()`, otherwise you can return a reference to the `ModelNotify` instance that you previously used in `attach_peer`:
+`attach_peer()` has been removed. Instead you must implement the
+[`fn model_tracker(&self) -> &dyn ModelTracker`](Model::model_tracker) function.
+If you have a constant model, then you can just return `&()`, otherwise you can return a reference
+to the [`ModelNotify`] instance that you previously used in `attach_peer`:
 
 Old code:
 
-```rust
+```rust,ignore
 fn attach_peer(&self, peer: sixtyfps::ModelPeer) {
     self.model_notify.attach_peer(peer);
 }
@@ -42,7 +48,7 @@ fn attach_peer(&self, peer: sixtyfps::ModelPeer) {
 
 New code:
 
-```rust
+```rust,ignore
 fn model_tracker(&self) -> &dyn ModelTracker {
     &self.model_notify
 }
@@ -50,13 +56,9 @@ fn model_tracker(&self) -> &dyn ModelTracker {
 
 or if your model is constant:
 
-```rust
+```rust,ignore
 fn model_tracker(&self) -> &dyn ModelTracker {
     &()
 }
 ```
 
-### Interpreter
-
-`Value::Array` was removed and `Value::Model` needs to be used instead.
-`CallCallbackError` was renamed to `InvokeCallbackError`.

sixtyfps_runtime/interpreter/lib.rs

@@ -74,6 +74,8 @@ mod dynamic_type;
 mod eval;
 mod eval_layout;
 mod global_component;
+#[cfg(doc)]
+pub mod migration;
 mod value_model;
 
 #[doc(inline)]

sixtyfps_runtime/interpreter/migration.rs

@@ -0,0 +1,13 @@
+// Copyright © SixtyFPS GmbH <info@sixtyfps.io>
+// SPDX-License-Identifier: (GPL-3.0-only OR LicenseRef-SixtyFPS-commercial)
+/*!
+# Migration from previous versions
+
+## Migration from v0.1.x
+
+* `Value::Array` was removed and [`Value::Model`] needs to be used instead.
+* `CallCallbackError` was renamed to [`InvokeCallbackError`].
+
+*/
+
+use crate::*;