Improve documentation

Author: koskja

feather/common/src/block_break.rs

@@ -1,3 +1,5 @@
+use std::mem;
+
 use base::{BlockKind, ItemStack, ValidBlockPosition};
 use ecs::{EntityBuilder, SysResult, SystemExecutor};
 use libcraft_items::EnchantmentKind;
@@ -14,6 +16,7 @@ pub enum BlockBreaker {
     Inactive,
 }
 impl BlockBreaker {
+    /// Create a new active instance pointing to `block_pos`. Calculates the time needed using `world.block_at(block_pos)` and `equipped_item`.
     pub fn new(
         world: &mut World,
         block_pos: ValidBlockPosition,
@@ -23,59 +26,69 @@ impl BlockBreaker {
             .map(Self::Active)
             .unwrap_or(Self::Inactive)
     }
+    /// If active, produces a `DestroyStateChange` event for the adequate position.
     pub fn destroy_change_event(&self) -> Option<DestroyStateChange> {
         Some(DestroyStateChange(self.position()?, self.destroy_stage()))
     }
+    /// If active or finished, returns the pointed to position.
     pub fn position(&self) -> Option<ValidBlockPosition> {
         match self {
             BlockBreaker::Active(a) => Some(a.position),
             BlockBreaker::Finished(f) => Some(f.position),
             BlockBreaker::Inactive => None,
         }
     }
+    /// If active, returns the underlying `ActiveBreaker`.
     pub fn active(&self) -> Option<&ActiveBreaker> {
         match self {
             Self::Active(a) => Some(a),
             _ => None,
         }
     }
+    /// If finished, returns the underlying `FinishedBreaker`.
     pub fn finished(&self) -> Option<&FinishedBreaker> {
         match self {
             Self::Finished(f) => Some(f),
             _ => None,
         }
     }
+    /// Progresses block breaking. Returns a (newly_finished, do_destry_state_change) tuple.
+    /// If this operation finishes block breaking, this turns `self` into `Self::Finished` with the same position.
     pub fn tick(&mut self) -> (bool, bool) {
         let (block_break, stage_update) = if let Self::Active(breaker) = self {
             breaker.tick()
         } else {
             (false, false)
         };
         if block_break {
-            let fin = match self {
-                Self::Active(a) => a.clone().finish(),
+            let fin = match mem::take(self) {
+                Self::Active(a) => a.finish(),
                 _ => unreachable!(),
             };
             *self = Self::Finished(fin);
         }
         (block_break, stage_update)
     }
+    /// Returns the block destroying progress in a range of 0 - 9. When inactive or finished, returns 10.
     pub fn destroy_stage(&self) -> u8 {
         match self {
             BlockBreaker::Active(a) => a.destroy_stage(),
             _ => 10,
         }
     }
+    /// Set `self` to `Self::Inactive`.
     pub fn cancel(&mut self) {
         *self = Self::Inactive;
     }
+    /// Check if the breaker points to `pos`. Returns `true` when `self` is `Self::Inactive`.
     pub fn matches_position(&self, pos: ValidBlockPosition) -> bool {
         match self {
             BlockBreaker::Active(a) => a.position == pos,
             BlockBreaker::Finished(f) => f.position == pos,
             BlockBreaker::Inactive => true,
         }
     }
+    /// Attempts to finish breaking the target block, optionally turning `self` into `Self::Finished`.
     pub fn try_finish(&mut self) -> Option<FinishedBreaker> {
         let this = self.clone();
         match this {
@@ -93,13 +106,19 @@ impl BlockBreaker {
         }
     }
 }
+impl Default for BlockBreaker {
+    fn default() -> Self {
+        Self::Inactive
+    }
+}
 #[derive(Clone)]
 pub struct FinishedBreaker {
     pub position: ValidBlockPosition,
     pub drop_item: bool,
     pub fake_finished: bool,
 }
 impl FinishedBreaker {
+    /// Breaks the targeted block and spawns its drops. TODO: make drops work.
     pub fn break_block(&self, game: &mut Game) -> SysResult {
         let target_block = match game.block(self.position) {
             Some(b) => b,