Add comments to `circuit-disband` guarded methods
This change adds doc comments to methods guarded by the
`circuit-disband` feature, including internal functions.
@@ -904,6 +904,8 @@ impl AdminServiceShared {
}
#[cfg(feature = "circuit-disband")]
+ /// Once a local `CircuitDisbandRequest` has been validated, the admin service may now proceed
+ /// to communicating with the remote circuit members to propose the disband change.
pub fn propose_disband(
&mut self,
payload: CircuitManagementPayload,
@@ -1180,6 +1182,10 @@ impl AdminServiceShared {
}
#[cfg(feature = "circuit-disband")]
+ /// Verify all members of the circuit to be disbanded are using a valid protocol version.
+ /// If all circuit members have agreed on a protocol version, the disband payload is moved into
+ /// the `pending_circuit_payloads` list for further processing. Otherwise, this payload is
+ /// added to the `pending_protocol_payloads` list to await all nodes' protocol agreement.
fn check_connected_peers_payload_disband(
&mut self,
members: &[SplinterNode],
@@ -2300,6 +2306,16 @@ impl AdminServiceShared {
}
#[cfg(feature = "circuit-disband")]
+ /// Validates a `CircuitDisbandRequest` using the following:
+ ///
+ /// - Validate the protocol version used by the submitter node. Currently, disbanding is only
+ /// available to nodes using `ADMIN_SERVICE_PROTOCOL_VERSION` 2.
+ /// - Validate the requester is authorized to propose a change for the requesting node
+ /// - Validate the signer's public key is authorized for the requesting node
+ /// - Validate a `CircuitProposal` with the same ID is not present
+ /// - Validate the circuit being disbanded has a valid `circuit_version` and `circuit_status`.
+ /// A circuit must have a `circuit_version` of at least 2 and a `circuit_status` of `Active`
+ /// in order to be disbanded.
fn validate_disband_circuit(
&self,
circuit: &Circuit,
@@ -2623,6 +2639,8 @@ impl AdminServiceShared {
}
#[cfg(feature = "circuit-disband")]
+ /// Makes the `CircuitProposal` associated with a `CircuitDisbandRequest` based on information
+ /// gathered from the currently active circuit that is specified in the disband request
fn make_disband_request_circuit_proposal(
&self,
circuit_id: &str,
