From f56e6e4320bd71365abaf6ac4c18a26d97817300 Mon Sep 17 00:00:00 2001 From: "W. J. van der Laan" Date: Wed, 17 Nov 2021 15:43:16 +0100 Subject: [PATCH] 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 --- src/netaddress.h | 6 ++++++ src/span.h | 8 ++++++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/src/netaddress.h b/src/netaddress.h index 2914e36bfb..2fb2b3625b 100644 --- a/src/netaddress.h +++ b/src/netaddress.h @@ -387,6 +387,12 @@ public: /** * 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 8885fc964f..84a3f4b140 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 + * , 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 arg); * * Foo(std::vector{1, 2, 3}); // Works