From f5e9f04aacab73ce2fe99d4b87fd22a6a3c53091 Mon Sep 17 00:00:00 2001
From: chrysn <chrysn@fsfe.org>
Date: Fri, 18 Mar 2022 11:42:10 +0100
Subject: [PATCH 1/7] doc: What is movability in types

See-Also: https://github.com/RIOT-OS/RIOT/issues/17817
---
 doc/doxygen/src/mainpage.md       |  1 +
 doc/doxygen/src/move-semantics.md | 76 +++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 doc/doxygen/src/move-semantics.md

diff --git a/doc/doxygen/src/mainpage.md b/doc/doxygen/src/mainpage.md
index 543b40cae3e7..671495778db4 100644
--- a/doc/doxygen/src/mainpage.md
+++ b/doc/doxygen/src/mainpage.md
@@ -237,6 +237,7 @@ Further information                                      {#further-information}
  - @ref porting-boards
  - @ref creating-modules
  - @ref advanced-build-system-tricks
+ - @ref move-semantics
 
 <!--
 Idea for this section: just name each of RIOT's main features/concepts and link
diff --git a/doc/doxygen/src/move-semantics.md b/doc/doxygen/src/move-semantics.md
new file mode 100644
index 000000000000..680ff7a864e8
--- /dev/null
+++ b/doc/doxygen/src/move-semantics.md
@@ -0,0 +1,76 @@
+Semantics of typedefs and moving their values {#typedef-and-move}
+=============================================
+
+This page describes general properties of types defined (`typedef`'d) in RIOT.
+It is mostly aimed at developers who alter or extend RIOT;
+API users can often ignore them if they stick to idiomatic C.
+
+This is being documented for consistenty within RIOT,
+and for the benefit of users who use RIOT
+from other languages (such as @rust using-rust "Rust" )
+or do other advanced things like implementing coroutines.
+
+Movability
+----------
+
+In C, generally,
+any type can technically be copied or moved,
+e.g. by returning it (which is possible but discouraged for larger structs),
+by assigning it to other variables
+or by using `memcpy` / `memmove`.
+
+Once a value has been passed through an initializer that takes it by reference,
+any further copy or move are generally *not* allowed any more,
+for the initializer might have done anything self-referential inside the value,
+or (more commonly) have inserted it into some linked list.
+
+Some types are described to be "movable".
+If a type is movable, its values may be moved to a different memory address
+even after it has been passed into a function by reference.
+Consequently, functions taking a reference
+may use the reference to access the value for the duration of the function,
+but not store the pointer anywhere.
+
+Is a type movable?
+------------------
+
+Types are generally not movable, unless they are
+
+* documented to be movable, or
+* taken by value (or returned by value) in public API functions (or preprocessor macros) that use the type.
+
+In addition,
+individual functions may state that they take a reference to be a short-lived,
+and make no requirements on the pointer's validity beyond the function's execution.
+(The @ref ztimer_is_set function might make such a statement).
+
+Examples
+--------
+
+The @ref ipv6_addr_t type is movable (because it is (TBD -- will be) documented to be):
+while it is frequently passed by referenced due to its sheer size,
+an application may just `memcpy` an address out of an obtained pointer and store it for later use
+(maybe along with a cache entry).
+
+In contrast, a @ref ztimer_t is not movable:
+a value may be created locally and populated (in theory even be moved around),
+but once it is passed to @ref ztimer_set by reference,
+that pointer needs to stay valid until further notice.
+Unlike with other types, this is documented in very explicit words on the function.
+
+More subtly, @ref vfs_DIR is also not movable (because that is the default for any type):
+Once passed into @ref vfs_opendir, its memory location needs to stay stable
+until @ref vfs_closedir releases it.
+Moving it is less likely to have ill-effects (because only the @ref pkg_littlefs2 uses the property),
+but users still need to treat it as not movable.
+
+In contrast, the file descriptors of the VFS are movable
+because they are returned by value in the @ref vfs_open function and passed into @ref vfs_close the same way.
+(Also, file descriptors are `int`, and as primitive types are not covered by this page).
+
+API stability
+-------------
+
+Removing the note from a function that the type is movable should be considered a breaking change.
+The change note on such an API change may say that
+"this change is unlikely to break idiomatic C applications".

From f0c1af387a798089e2bcdba754af44a203874c25 Mon Sep 17 00:00:00 2001
From: chrysn <chrysn@fsfe.org>
Date: Fri, 18 Mar 2022 11:58:59 +0100
Subject: [PATCH 2/7] fixup! doc: What is movability in types

Co-authored-by: Kaspar Schleiser <kaspar@schleiser.de>
---
 doc/doxygen/src/move-semantics.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/doxygen/src/move-semantics.md b/doc/doxygen/src/move-semantics.md
index 680ff7a864e8..dd60bfc8b736 100644
--- a/doc/doxygen/src/move-semantics.md
+++ b/doc/doxygen/src/move-semantics.md
@@ -5,7 +5,7 @@ This page describes general properties of types defined (`typedef`'d) in RIOT.
 It is mostly aimed at developers who alter or extend RIOT;
 API users can often ignore them if they stick to idiomatic C.
 
-This is being documented for consistenty within RIOT,
+This is being documented for consistency within RIOT,
 and for the benefit of users who use RIOT
 from other languages (such as @rust using-rust "Rust" )
 or do other advanced things like implementing coroutines.

From 10b449ac7b0ab25829e10a866668bb8427e22b2e Mon Sep 17 00:00:00 2001
From: chrysn <chrysn@fsfe.org>
Date: Fri, 18 Mar 2022 11:59:20 +0100
Subject: [PATCH 3/7] fixup! doc: What is movability in types

Co-authored-by: Kaspar Schleiser <kaspar@schleiser.de>
---
 doc/doxygen/src/move-semantics.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/doxygen/src/move-semantics.md b/doc/doxygen/src/move-semantics.md
index dd60bfc8b736..3797fb7bc150 100644
--- a/doc/doxygen/src/move-semantics.md
+++ b/doc/doxygen/src/move-semantics.md
@@ -40,7 +40,7 @@ Types are generally not movable, unless they are
 * taken by value (or returned by value) in public API functions (or preprocessor macros) that use the type.
 
 In addition,
-individual functions may state that they take a reference to be a short-lived,
+individual functions may state that they take a reference to be short-lived,
 and make no requirements on the pointer's validity beyond the function's execution.
 (The @ref ztimer_is_set function might make such a statement).
 

From abdaf2f5d9c8f293b6cb855b3d7047a72fd10742 Mon Sep 17 00:00:00 2001
From: Kaspar Schleiser <kaspar@schleiser.de>
Date: Fri, 18 Mar 2022 14:12:53 +0100
Subject: [PATCH 4/7] squash! / Add 'why do we care'

---
 doc/doxygen/src/move-semantics.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/doc/doxygen/src/move-semantics.md b/doc/doxygen/src/move-semantics.md
index 680ff7a864e8..150459ecf66a 100644
--- a/doc/doxygen/src/move-semantics.md
+++ b/doc/doxygen/src/move-semantics.md
@@ -31,6 +31,22 @@ Consequently, functions taking a reference
 may use the reference to access the value for the duration of the function,
 but not store the pointer anywhere.
 
+Why do we care?
+---------------
+
+The C compiler in general doesn't move around
+data that has been allocated on stack or on the heap
+by itself,
+so movability is usually not something that
+ideomatic C needs to deal with.
+
+The Rust compiler does move data around,
+if it deems it beneficial for optimization.
+
+As most of RIOT's C APIs are being used by Rust through wrappers,
+movability of a type needs to be specified
+in order to no force Rust to assume *may never move* on *all* types.
+
 Is a type movable?
 ------------------
 

From f24074c4f196dadc38a6bc36203308218392329e Mon Sep 17 00:00:00 2001
From: chrysn <chrysn@fsfe.org>
Date: Fri, 18 Mar 2022 14:58:56 +0100
Subject: [PATCH 5/7] fixup! doc: What is movability in types

---
 doc/doxygen/src/move-semantics.md | 31 ++++++++++++++++++-------------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/doc/doxygen/src/move-semantics.md b/doc/doxygen/src/move-semantics.md
index 361c2d72f896..be90d90cd117 100644
--- a/doc/doxygen/src/move-semantics.md
+++ b/doc/doxygen/src/move-semantics.md
@@ -5,17 +5,12 @@ This page describes general properties of types defined (`typedef`'d) in RIOT.
 It is mostly aimed at developers who alter or extend RIOT;
 API users can often ignore them if they stick to idiomatic C.
 
-This is being documented for consistency within RIOT,
-and for the benefit of users who use RIOT
-from other languages (such as @rust using-rust "Rust" )
-or do other advanced things like implementing coroutines.
-
 Movability
 ----------
 
 In C, generally,
 any type can technically be copied or moved,
-e.g. by returning it (which is possible but discouraged for larger structs),
+e.g. by returning it,
 by assigning it to other variables
 or by using `memcpy` / `memmove`.
 
@@ -34,18 +29,28 @@ but not store the pointer anywhere.
 Why do we care?
 ---------------
 
-The C compiler in general doesn't move around
-data that has been allocated on stack or on the heap
-by itself,
-so movability is usually not something that
-ideomatic C needs to deal with.
+In C we avoid passing large items by value,
+and consequently pass pointers around to initialize and finalize values;
+consequently, a stable address of a value is often around and ready to be used.
+
+In @rust using-rust "Rust" there are no restrictions on the size of return values,
+and logically moving values makes it easy to uphold [RAII] guarantees.
+(The Rust compiler will often use its knowledge of the program to not make values actually move,
+but neither is that guaranteed nor can it be reliably observed).
 
-The Rust compiler does move data around,
-if it deems it beneficial for optimization.
+[RAII]: https://en.wikipedia.org/wiki/Resource_acquisition_is_initialization
 
 As most of RIOT's C APIs are being used by Rust through wrappers,
 movability of a type needs to be specified
 in order to no force Rust to assume *may never move* on *all* types.
+Types that may not move but are allocated by Rust
+require more [verbose and complicated] application code.
+
+[verbose and complicated]: https://doc.rust-lang.org/core/pin/index.html
+
+In addition to the benefits for the Rust wrappers,
+the documenting movability helps keeping RIOT internally consistent,
+and assists in other advanced use cases like coroutines.
 
 Is a type movable?
 ------------------

From 31553c223896d8fe52e9ed9b734348652c1f8378 Mon Sep 17 00:00:00 2001
From: chrysn <chrysn@fsfe.org>
Date: Fri, 18 Mar 2022 15:03:34 +0100
Subject: [PATCH 6/7] fixup! doc: What is movability in types

ivp6_addr_t needs no dedicated docs
---
 doc/doxygen/src/move-semantics.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/doxygen/src/move-semantics.md b/doc/doxygen/src/move-semantics.md
index be90d90cd117..d95e250e675e 100644
--- a/doc/doxygen/src/move-semantics.md
+++ b/doc/doxygen/src/move-semantics.md
@@ -68,7 +68,7 @@ and make no requirements on the pointer's validity beyond the function's executi
 Examples
 --------
 
-The @ref ipv6_addr_t type is movable (because it is (TBD -- will be) documented to be):
+The @ref ipv6_addr_t type is movable (because @ref IPV6_ADDR_LOOPBACK returns one by value):
 while it is frequently passed by referenced due to its sheer size,
 an application may just `memcpy` an address out of an obtained pointer and store it for later use
 (maybe along with a cache entry).

From 6971170c63b7c4cce4e50236281ccfdc74c39d33 Mon Sep 17 00:00:00 2001
From: chrysn <chrysn@fsfe.org>
Date: Fri, 18 Mar 2022 15:05:02 +0100
Subject: [PATCH 7/7] fixup! doc: What is movability in types

---
 doc/doxygen/src/move-semantics.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/doxygen/src/move-semantics.md b/doc/doxygen/src/move-semantics.md
index d95e250e675e..5122d1566427 100644
--- a/doc/doxygen/src/move-semantics.md
+++ b/doc/doxygen/src/move-semantics.md
@@ -65,6 +65,10 @@ individual functions may state that they take a reference to be short-lived,
 and make no requirements on the pointer's validity beyond the function's execution.
 (The @ref ztimer_is_set function might make such a statement).
 
+The lack of a required destructor / finalizer / closing function for a type
+is not a reliable indicator that a type is movable
+(but it is a pretty good hint).
+
 Examples
 --------