Add check flags protocols docs

protocols/v2/subprotocols/common-messages/src/setup_connection.rs

@@ -2,13 +2,19 @@
 use alloc::vec::Vec;
 #[cfg(not(feature = "with_serde"))]
 use binary_sv2::{
- binary_codec_sv2, binary_codec_sv2::CVec, decodable::DecodableField, decodable::FieldMarker,
- free_vec, Error,
+ binary_codec_sv2,
+ binary_codec_sv2::CVec,
+ decodable::DecodableField,
+ decodable::FieldMarker,
+ free_vec,
+ Error,
 };
-use binary_sv2::{Deserialize, GetSize, Serialize, Str0255};
+use binary_sv2::{ Deserialize, GetSize, Serialize, Str0255 };
 use const_sv2::{
- SV2_JOB_DISTR_PROTOCOL_DISCRIMINANT, SV2_JOB_NEG_PROTOCOL_DISCRIMINANT,
- SV2_MINING_PROTOCOL_DISCRIMINANT, SV2_TEMPLATE_DISTR_PROTOCOL_DISCRIMINANT,
+ SV2_JOB_DISTR_PROTOCOL_DISCRIMINANT,
+ SV2_JOB_NEG_PROTOCOL_DISCRIMINANT,
+ SV2_MINING_PROTOCOL_DISCRIMINANT,
+ SV2_TEMPLATE_DISTR_PROTOCOL_DISCRIMINANT,
 };
 use core::convert::TryFrom;
 #[cfg(not(feature = "with_serde"))]
@@ -69,6 +75,17 @@ impl<'decoder> SetupConnection<'decoder> {
  // [1] [1] -> true
  // [0] [1] -> false
  Protocol::MiningProtocol => {
+ // Evaluates protocol requirements based on flag bits.
+ //
+ // Checks if the current protocol meets the required flags for work selection and version rolling
+ // by reversing the bits of `available_flags` and `required_flags`. It extracts the 30th and 29th
+ // bits to determine if work selection and version rolling are needed.
+ //
+ // Returns `true` if:
+ // - The work selection requirement is satisfied or not needed.
+ // - The version rolling requirement is satisfied or not needed.
+ //
+ // Otherwise, returns `false`.
  let available = available_flags.reverse_bits();
  let required_flags = required_flags.reverse_bits();
  let requires_work_selection_passed = required_flags >> 30 > 0;
@@ -85,16 +102,20 @@ impl<'decoder> SetupConnection<'decoder> {
  work_selection && version_rolling
  }
  Protocol::JobDeclarationProtocol => {
+ // Determines if asynchronous job mining is required based on flag bits.
+ //
+ // Reverses the bits of `available_flags` and `required_flags`, extracts the 31st bit from each,
+ // and evaluates if the condition is met using these bits. Returns `true` or `false` based on:
+ // - True if `requires_async_job_mining_self` is true, or both are true.
+ // - False if `requires_async_job_mining_self` is false and `requires_async_job_mining_passed` is true.
+ // - True otherwise.
  let available = available_flags.reverse_bits();
  let required = required_flags.reverse_bits();
 
  let requires_async_job_mining_passed = (required >> 31) & 1 > 0;
  let requires_async_job_mining_self = (available >> 31) & 1 > 0;
 
- match (
- requires_async_job_mining_self,
- requires_async_job_mining_passed,
- ) {
+ match (requires_async_job_mining_self, requires_async_job_mining_passed) {
  (true, true) => true,
  (true, false) => true,
  (false, true) => false,
@@ -327,18 +348,17 @@ impl<'a> From<Protocol> for binary_sv2::encodable::EncodableField<'a> {
 #[cfg(not(feature = "with_serde"))]
 impl<'decoder> binary_sv2::Decodable<'decoder> for Protocol {
  fn get_structure(
- _: &[u8],
+ _: &[u8]
  ) -> core::result::Result<alloc::vec::Vec<FieldMarker>, binary_sv2::Error> {
  let field: FieldMarker = (0_u8).into();
  Ok(alloc::vec![field])
  }
  fn from_decoded_fields(
- mut v: alloc::vec::Vec<DecodableField<'decoder>>,
+ mut v: alloc::vec::Vec<DecodableField<'decoder>>
  ) -> core::result::Result<Self, binary_sv2::Error> {
  let val = v.pop().ok_or(binary_sv2::Error::NoDecodableFieldPassed)?;
  let val: u8 = val.try_into()?;
- val.try_into()
- .map_err(|_| binary_sv2::Error::ValueIsNotAValidProtocol(val))
+ val.try_into().map_err(|_| binary_sv2::Error::ValueIsNotAValidProtocol(val))
  }
 }
 
@@ -389,16 +409,16 @@ impl GetSize for SetupConnectionSuccess {
 #[cfg(feature = "with_serde")]
 impl<'d> GetSize for SetupConnection<'d> {
  fn get_size(&self) -> usize {
- self.protocol.get_size()
- + self.min_version.get_size()
- + self.max_version.get_size()
- + self.flags.get_size()
- + self.endpoint_host.get_size()
- + self.endpoint_port.get_size()
- + self.vendor.get_size()
- + self.hardware_version.get_size()
- + self.firmware.get_size()
- + self.device_id.get_size()
+ self.protocol.get_size() +
+ self.min_version.get_size() +
+ self.max_version.get_size() +
+ self.flags.get_size() +
+ self.endpoint_host.get_size() +
+ self.endpoint_port.get_size() +
+ self.vendor.get_size() +
+ self.hardware_version.get_size() +
+ self.firmware.get_size() +
+ self.device_id.get_size()
  }
 }
 #[cfg(test)]
@@ -412,21 +432,13 @@ mod test {
  let protocol = crate::Protocol::MiningProtocol;
  let flag_available = 0b_0000_0000_0000_0000_0000_0000_0000_0000;
  let flag_required = 0b_0000_0000_0000_0000_0000_0000_0000_0001;
- assert!(SetupConnection::check_flags(
- protocol,
- flag_available,
- flag_required
- ));
+ assert!(SetupConnection::check_flags(protocol, flag_available, flag_required));
 
  let protocol = crate::Protocol::JobDeclarationProtocol;
 
  let available_flags = 0b_1000_0000_0000_0000_0000_0000_0000_0000;
  let required_flags = 0b_1000_0000_0000_0000_0000_0000_0000_0000;
- assert!(SetupConnection::check_flags(
- protocol,
- available_flags,
- required_flags
- ));
+ assert!(SetupConnection::check_flags(protocol, available_flags, required_flags));
  }
 
  #[test]