95fb4e01f9 Document cargo features (Martin Habovstiak)
Pull request description:
This documents cargo features in two ways: explictly in text and in code
using `#[doc(cfg(...))]` attribute where possible. Notably, this is
impossible for `serde` derives. The attribute is contitional and only
activated for docs.rs or explicit local builds.
This change also adds `package.metadata.docs.rs` field to `Cargo.toml`
which instructs docs.rs to build with relevant features and with
`docsrs` config activated enabling `#[doc(cfg(...))] attributes.
I also took the opportunity to fix a few missing spaces in nearby code.
Notes for reviewers:
* To build and look at result locally run: `RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --features std,secp-recovery,base64,rand,use-serde,bitcoinconsensus --open` (don't confuse `RUSTDOCFLAGS` with `RUSTFLAGS` - took me a while to figure that out 😞)
* You should see needed features being called out - e.g. in `Script::verify`
* More information and some screenshots: https://github.com/rust-lang/cargo/issues/8103#issuecomment-653154049
* For an example why this matters see: https://github.com/Kixunil/loptos/issues/1😉
* Serde issue: https://github.com/serde-rs/serde/issues/2063
ACKs for top commit:
dr-orlovsky:
ACK 95fb4e01f9
apoelstra:
ACK 95fb4e01f9
Tree-SHA512: 4d6428bfa05cbeb2d8737f0239aa1836b5f36f4b040e1ac5e0862663c4ea783711d122182dd8313913fd593ab224915bd8def5e268b272215bee2c9856a27674
This documents cargo features in two ways: explictly in text and in code
using `#[doc(cfg(...))]` attribute where possible. Notably, this is
impossible for `serde` derives. The attribute is contitional and only
activated for docs.rs or explicit local builds.
This change also adds `package.metadata.docs.rs` field to `Cargo.toml`
which instructs docs.rs to build with relevant features and with
`docsrs` config activated enabling `#[doc(cfg(...))] attributes.
I also took the opportunity to fix a few missing spaces in nearby code.
This refactors the code to make it possible to use `get_or_insert_with`
instead of unwrapping in `segwit_cache()`. To achieve it `common_cache`
is refactored into two functions: one taking only the required borrows
and the original calling the new one. `segwit_cache` then calls the new
function so that borrows are OK.
Apart from removing unwrap, this avoids calling `common_cache` multiple
times.
There was a question whether this is equally performant. There are
multiple good reasons why it should be:
1. `get_or_insert_with` is marked `#[inline]`
2. Any good optimizer will inline a function that is used exactly once
3. 1 and 2 conclude that the closure will get inlined
4. Computing self.tx can then be moved to the only branch where it is
required.
5. Even if get_or_insert_with didn't get optimized, which is extremely
unlikely, the `tx` field is at the beginning of the struct and it
probably has pointer alignment (`Deref` suggests it's a pointer).
Alignment larger than pointer is not used, so we can expect the
fields to be ordered as-defined. (This is not guaranteed by Rust but
there's not good reason to change the order in this case.) We can
assume that offset to tx is zero in most cases which means no
computation is actually needed so the expression before closure is
no-op short of passing it into the closure as an argument.
At the time of writing `#[inline]` can be seen at
https://doc.rust-lang.org/src/core/option.rs.html#933
Instead of using magic numbers we can define constants for the address
prefix bytes. This makes it easier for future readers of the code to see
what these values are if they don't know them and/or see that they are
correct if they do know them.
Vikas S Shetty
Andrew Poelstra
Dr Maxim Orlovsky
Martin Habovstiak
Ben Carman
sanket1729
Riccardo Casatta
Devrandom
Tobin Harding