Merge bitcoin/bitcoin#22881: doc: provide context for CNetAddr::UnserializeV1Array() and span.h with lifetimebound

33c6a208a9e2512a174c99c224a933a59f091bc2 span, doc: provide span.h context and explain lifetimebound definition (Jon Atack)
d14395bc5db55331115fa3c1e71741d1de7f092f net, doc: provide context for UnserializeV1Array() (Jon Atack)

Pull request description:

  Add contextual documentation for developers and future readers of the code regarding
  - CNetAddr::UnserializeV1Array (see #22140)
  - Span and why it defines Clang lifetimebound locally rather than using the one in attributes.h

ACKs for top commit:
  laanwj:
    Documentation review ACK 33c6a208a9e2512a174c99c224a933a59f091bc2

Tree-SHA512: cb8e6a6c23b36c9ef7499257e97c5378ec895bb9122b79b63b572d9721a1ae6ce6c0be7ad61bdf976c255527ae750fc9ff4b3e03c07c6c797d14dbc82ea9fb3a

2 files changed, 12 insertions, 2 deletions

diff --git a/src/netaddress.h b/src/netaddress.h
index b0b1c5ca9e..a5b74eb35b 100644
--- a/src/netaddress.h
+++ b/src/netaddress.h
@@ -385,6 +385,12 @@ private:
 
     /**
      * Unserialize from a pre-ADDRv2/BIP155 format from an array.
+     *
+     * This function is only called from UnserializeV1Stream() and is a wrapper
+     * for SetLegacyIPv6(); however, we keep it for symmetry with
+     * SerializeV1Array() to have pairs of ser/unser functions and to make clear
+     * that if one is altered, a corresponding reverse modification should be
+     * applied to the other.
      */
     void UnserializeV1Array(uint8_t (&arr)[V1_SERIALIZATION_SIZE])
     {
diff --git a/src/span.h b/src/span.h
index 168162e309..1e347846d8 100644
--- a/src/span.h
+++ b/src/span.h
@@ -30,7 +30,11 @@
 
 /** A Span is an object that can refer to a contiguous sequence of objects.
  *
- * It implements a subset of C++20's std::span.
+ * This file implements a subset of C++20's std::span.  It can be considered
+ * temporary compatibility code until C++20 and is designed to be a
+ * self-contained abstraction without depending on other project files. For this
+ * reason, Clang lifetimebound is defined here instead of including
+ * <attributes.h>, which also defines it.
  *
  * Things to be aware of when writing code that deals with Spans:
  *
@@ -60,7 +64,7 @@
  *   types that expose a data() and size() member function), functions that
  *   accept a Span as input parameter can be called with any compatible
  *   range-like object. For example, this works:
-*
+ *
  *       void Foo(Span<const int> arg);
  *
  *       Foo(std::vector<int>{1, 2, 3}); // Works