// (lightly edited for clarity)
impl Encoder {
  ..

  /// Encode the provided bits into the output time-domain IQ samples.
  fn encode(
    &mut self,
    dst: &mut [IQ],
    src: &Vector,
  ) -> Result<Burst, Error> {
    let src = {
      let mut raw = Vector::new(self.fec.message_len());

      // Set `raw`'s data bits, compute and set LDPC
      // checkbits.
      self.fec.add(&mut raw, src);

      // Apply whitening, and return
      raw.xor(&self.whitening)
    };

    // copy in the precomputed schmidl-cox preamble to `dst`
    let preamble_len = self.preamble_iq.len();
    dst[..preamble_len].copy_from_slice(&self.preamble_iq);

    // allocate a new (frequency domain) 'Burst' container.
    let mut burst = Burst::new(
      &self.mode.ofdm.plan,
      self.mode.ofdm.symbols
    );

    // modulate bits from 'src' as iq, and set each
    // data subcarrier for each ofdm symbol in the
    // burst.
    self.burst_encoder.multiplex(&mut burst, &src);

    // convert from frequency-domain data into time
    // domain iq samples, writing out ofdm symbols
    // and cyclic prefixes to `dst`.
    self.burst_encoder
      .transform(&mut dst[preamble_len..], &burst)?;

    // normalize all IQ samples; the maximum magnitude
    // in the IQ buffer may be very small, which weakens
    // our transmitted signal. Scale all IQ samples such
    // that the maximum IQ sample magnitude will be '1.0'.
    dst.norm();

    Ok(burst)
  }
}

#[derive(Clone)]
pub struct FrameBuffer {
    /// Corrected IQ samples
    pub samples: Samples,

    /// post-correction OFDM burst
    pub burst: Burst,

    /// demodulated bits from the OFDM burst
    pub bits: Vector,

    /// demodulated bits from the OFDM burst,
    /// after FEC, and cleaned
    pub raw_bits: Vector,

    /// Layer 2 contents of the Frame
    pub contents: Vec<u8>,
}

// (lightly edited for clarity)

impl Decoder {
  ..

  /// Process incoming IQ for Pigeon Bursts, and
  /// demodulate them.
  pub fn decode(
    &mut self,
    buf: &[IQ],
  ) -> Result<Vec<(Detection, &FrameBuffer)>, Error> {
   let mut ret = Vec::new();
   let mode = self.scanner.mode().clone();

   // reset the "valid frame buffer count" back to 0
   self.frames.reset();

   // call the scanner and get scan detections for
   // this block of iq (`buf`)
   for detection in self.scanner.scan(buf) {
     // for each detection, we're (only) going to process
     // the iq snippit, but pass along the metadata
     // such as SNR.
     let ScanDetection {
       snippit,
       snr,
       range,
       m,
     } = detection;

     // grab the next free frame buffer to work within.
     let frame_buffer = self.frames.next_mut();

     // Copy the snippit into the frame buffer (a mutable
     // location)
     frame_buffer.samples.copy_from_slice(snippit);

     // estimate the frequency offset based on the
     // Burst's Schmidl-Cox preamble.
     let preamble_fo = preamble::estimate_frequency_offset(
       &mode.preamble,
       mode.rate,
       &frame_buffer.samples[..mode.preamble.samples()],
     );

     // Shift the IQ stream by the estimated frequency
     // offset -- hopefully we're closer to 0Hz
     frame_buffer.samples.shift(mode.rate, preamble_fo);

     // estimate the frequency offset based on the
     // each burst's **cyclic prefix** -- exactly like
     // we did with the Burst Schmidl-Cox preamble,
     // but this time on each OFDM symbol.
     let ofdm_fo = ofdm::estimate_frequency_offset(
       &mode.ofdm,
       mode.rate,
       &frame_buffer.samples[mode.preamble.samples()..],
     );

     // Shift the IQ stream closer yet; hopefully this
     // is a very small nudge even closer still to 0Hz.
     frame_buffer.samples.shift(mode.rate, ofdm_fo);

     // Do a bunch of inverse fft operations for each
     // OFDM symbol, filling the frequency-domain Symbol
     // structs in `frame_buffer.burst` (Burst) struct.
     //
     // this will also do channel estimation and
     // correction before returning.
     self
       .decoder
       .transform(
         &mut frame_buffer.burst,
         &frame_buffer.samples[mode.preamble.samples()..],
       )?;

     // "demultiplex" each data subcarrier's frequency-domain
     // IQ constellation point, setting the correct bit range.
     self.decoder.demultiplex(
       &mut frame_buffer.raw_bits,
       &frame_buffer.burst
     );

     // unapply whitening by XOR-ing the buffer with
     // the well-known whitening vector.
     frame_buffer.raw_bits = frame_buffer.raw_bits.xor(
       &self.whitening);

     // verify that the LDPC message(s) are all correct,
     // and if so, concatanate the the data bits (no check
     // bits) to the `bits` vector.
     if self.fec.decode(
       &mut frame_buffer.bits,
       &frame_buffer.raw_bits
     ).is_err() {
       // this is where invalid packets fail. we gave it a good go.
       // next packet please.
       continue;
     }

     // copy the raw bits out, as bytes, to the `contents` buffer.
     frame_buffer.bits.copy_as_bytes(&mut frame_buffer.contents);

     // store metadata/metrics on the demodulation.
     ret.push(Detection {
       m,
       snr,
       index: range.start,
     });

     // save the contents of this frame buffer (don't
     // reuse this buffer next go-around).
     self.frames.save();
   }

   // We're going to take out the borrow on the frame at
   // the end since we don't want to deal with telling the
   // compiler via code gymnastics that the mut and non-mut
   // borrows are OK since they're non-overlapping.
   Ok(ret.into_iter().zip(self.frames.iter()).collect())
  }
}