From 0760fb2da3dc15e1d44bfac72d6393de837cf0e2 Mon Sep 17 00:00:00 2001
From: Mikolaj Wielgus <wielgusmikolaj@gmail.com>
Date: Mon, 2 Dec 2024 01:17:43 +0100
Subject: [PATCH] docs(drawing,router): rephrase docstrings some more

---
 src/drawing/head.rs   | 20 +++++++++++++-------
 src/router/navcord.rs | 10 +++++++---
 2 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/src/drawing/head.rs b/src/drawing/head.rs
index 88a9e9c..2cf009a 100644
--- a/src/drawing/head.rs
+++ b/src/drawing/head.rs
@@ -16,8 +16,8 @@ pub trait GetFace {
 }
 
 /// The head is the working part of the running end of the currently routed
-/// band. Both bare and cane heads have a face, which is the fixed dot that
-/// terminates the running end.
+/// band. Both bare and cane heads have a face, which is the dot that terminates
+/// the running end.
 #[enum_dispatch(GetFace)]
 #[derive(Debug, Clone, Copy)]
 pub enum Head {
@@ -33,8 +33,9 @@ impl<'a, CW: Copy, R: AccessRules> MakeRef<'a, HeadRef<'a, CW, R>, Drawing<CW, R
 
 /// The head is bare when the routed band is not pulled out (i.e. is of zero
 /// length). This happens on the first routing step and when the routed band was
-/// contracted due to the routing algorithm backtracking. In these situations a
-/// cane head cannot be used because there is obviously no cane behind the face.
+/// completely contracted due to the routing algorithm backtracking. In these
+/// situations a cane head cannot be used because there is obviously no cane
+/// behind the face, and the face itself is fixed instead of loose.
 #[derive(Debug, Clone, Copy)]
 pub struct BareHead {
     pub face: FixedDotIndex,
@@ -46,9 +47,14 @@ impl GetFace for BareHead {
     }
 }
 
-/// The head is a cane head when the routed band is of nonzero length (i.e. is
-/// pulled out). It differs from the bare head by having a `cane` member, which
-/// is the terminal cane on the running end of the currently routed band.
+/// The head is a cane head when the routed band is pulled out (i.e. is of
+/// non-zero length). It differs from a bare head by having a `cane` member,
+/// which is the terminal cane on the running end of the currently routed band.
+///
+/// You can think of the cane head's cane as of a very long neck, though in
+/// anatomy the neck is not considered to be a part of the head, and the face,
+/// which here would be the head proper, itself has the same width as the cane,
+/// also unlike a real head.
 #[derive(Debug, Clone, Copy)]
 pub struct CaneHead {
     pub face: LooseDotIndex,
diff --git a/src/router/navcord.rs b/src/router/navcord.rs
index 5ffc215..1ff95e0 100644
--- a/src/router/navcord.rs
+++ b/src/router/navcord.rs
@@ -15,10 +15,14 @@ use super::{
     navmesh::{BinavvertexNodeIndex, Navmesh, NavvertexIndex},
 };
 
+/// The navcord is a structure that holds the movable non-borrowing data of the
+/// currently running routing process.
+///
+/// The name "navcord" is a shortening of "navigation cord", by analogy to
+/// "navmesh" being a shortening of "navigation mesh".
 #[derive(Debug)]
-/// Stepper for the Navcord.
 pub struct NavcordStepper {
-    /// The currently chosen path.
+    /// The currently attempted path.
     pub path: Vec<NavvertexIndex>,
     /// Head of the routed band.
     pub head: Head,
@@ -27,7 +31,7 @@ pub struct NavcordStepper {
 }
 
 impl NavcordStepper {
-    /// Create new Navigation Cord instance
+    /// Creates a new navcord.
     pub fn new(
         source: FixedDotIndex,
         source_navvertex: NavvertexIndex,