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
This commit is contained in:
W. J. van der Laan 2021-11-17 15:43:16 +01:00 committed by pasta
parent cca91c48c7
commit f56e6e4320
No known key found for this signature in database
GPG Key ID: 52527BEDABE87984
2 changed files with 12 additions and 2 deletions

View File

@ -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])
{

View File

@ -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