cuprate_blockchain/ops/
macros.rs

1//! Macros.
2//!
3//! These generate repetitive documentation
4//! for all the functions defined in `ops/`.
5
6//---------------------------------------------------------------------------------------------------- Documentation macros
7/// Generate documentation for the required `# Error` section.
8macro_rules! doc_error {
9    () => {
10        r"# Errors
11This function returns [`cuprate_database::RuntimeError::KeyNotFound`] if the input (if applicable) doesn't exist or other `RuntimeError`'s on database errors."
12    };
13}
14pub(super) use doc_error;
15
16/// Generate `# Invariant` documentation for internal `fn`'s
17/// that should be called directly with caution.
18macro_rules! doc_add_block_inner_invariant {
19    () => {
20            r"# ⚠️ Invariant ⚠️
21This function mainly exists to be used internally by the parent function [`crate::ops::block::add_block`].
22
23`add_block()` makes sure all data related to the input is mutated, while
24this function _does not_, it specifically mutates _particular_ tables.
25
26This is usually undesired - although this function is still available to call directly.
27
28When calling this function, ensure that either:
291. This effect (incomplete database mutation) is what is desired, or that...
302. ...the other tables will also be mutated to a correct state"
31    };
32}
33pub(super) use doc_add_block_inner_invariant;
34
35/// Generate `# Invariant` documentation for internal alt block `fn`'s
36/// that should be called directly with caution.
37///
38/// This is pretty much the same as [`doc_add_block_inner_invariant`],
39/// it's not worth the effort to reduce the duplication.
40macro_rules! doc_add_alt_block_inner_invariant {
41    () => {
42            r"# ⚠️ Invariant ⚠️
43This function mainly exists to be used internally by the parent function [`crate::ops::alt_block::add_alt_block`].
44
45`add_alt_block()` makes sure all data related to the input is mutated, while
46this function _does not_, it specifically mutates _particular_ tables.
47
48This is usually undesired - although this function is still available to call directly.
49
50When calling this function, ensure that either:
511. This effect (incomplete database mutation) is what is desired, or that...
522. ...the other tables will also be mutated to a correct state"
53    };
54}
55pub(super) use doc_add_alt_block_inner_invariant;