added some documentation

Cargo.toml

@@ -1,12 +1,14 @@
 [package]
 name = "etherage"
-categories = ["science::robotics", "no-std", "network-programming"]
+categories = ["science::robotics", "network-programming"]
+authors = ["Jimy Byerley <[email protected]>", "CendreQuasar540"]
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 readme = "README.md"
 description = "An EtherCAT master in pure-Rust very close to the ethercat nature"
-keywords = ["no-std", "beckhoff", "ethercat", "igh", "soem", "omron"]
+keywords = ["ethercat", "ethernet", "realtime", "robotics", "servodrive"]
+url = "https://github.com/jimy-byerley/etherage"
 resolver = "2"
 
 [dependencies]

readme.md

@@ -78,13 +78,15 @@ This crate aims to bring yet a other implementation of an Ethercat master, The [
 
 - if connecting to an ethercat segment with a direct ethernet connection (the common practice), you need permissions to open a raw-socket (usually *root* access)
 - if connecting to an ethercat segment through a UDP socket, any normal user can proceed.
-- no special OS dependency or configuration is needed, only what is `Cargo.toml`
+- no special OS dependency or configuration is needed, only what is in [`Cargo.toml`](Cargo.toml)
 
 ### take the path
 
 The best way to take a tour of what `etherage` can do is to look at the [examples](examples)
 
-First: check that the example takes the right network interface in the desired example `fn main`: by default it is `eno1`. Then compile and run:
+First: check that the example takes the right network interface (default is `eno1`) in the main of the desired example.
+
+Then compile and run:
 
 ```shell
 cargo build --example slaves_discovery

src/mapping.rs

@@ -17,7 +17,7 @@
             let mut channel = slave.channel(sdo::SyncChannel{ index: 0x1c12, direction: SyncDirection::Read, num: 4 });
                 let mut pdo = channel.push(sdo::Pdo{ index: 0x1600, num: 10 });
                     let status = pdo.push(Sdo::<u16>::complete(0x6041));
-                    let error = pdo.push(Sdo::<u16>::complete(0x603f));
+                    let position = pdo.push(Sdo::<i32>::complete(0x6064));
                 // possibly other PDOs
             // possibly other sync managers
         // possibly other slaves
@@ -28,7 +28,7 @@
     
     // realtime exchanges
     group.exchange().await;
-    group.set(position, group.get(position)+velocity);
+    group.get(position);
     ```
     
     ## Principle

src/registers.rs

@@ -152,19 +152,50 @@ pub struct AlStatus {
 data::bilge_pdudata!(AlStatus, u8);
 
 /**
-    the current operation states on several devices
+    the current operation state on one device.
     
     This is the enum version, useful when communicating with one slave only
+    
+    Except [Self::Bootstrap], changing to any mode can be requested from any upper mode or from the preceding one.
 
     ETG.1000.6 table 9
 */
 #[bitsize(4)]
 #[derive(TryFromBits, Debug, Copy, Clone, Eq, PartialEq)]
 pub enum AlState {
+    /**
+        Transitional state meaning the slave is booting up and ready for nothing yet. The slave should normally reach the [Self::Init] state within seconds.
+        
+        It cannot be requested, nor changed while it is active.
+    */
+    Bootstrap = 3,
+    /**
+        The init mode allows to set many communication registers, like the salve address, the mailbox setup, etc.
+        
+        This mode should be used at the beginning of a communication. Only registers can be used.
+    */
     Init = 1,
+    /**
+        the pre operational mode allows mailbox communication, which is mendatory to configure some slaves before realtime operations. Most functions are enabled but not realtime.
+        
+        Communication setup via registers is no more allowed in this mode.
+    */
     PreOperational = 2,
-    Bootstrap = 3,
+    /**
+        Mode allowing realtime operations, except that commands sent to the slaves via its mapping will not be executed.
+        
+        This is a kind of read-only temporary mode before [Self::Operational], that can be useful for initializing control loops on the master side while their outputs are ignored.
+        
+        Mapping is no more allowed in this state, nor communication setup via registers.
+    */
     SafeOperational = 4,
+    /**
+        Realtime operations running
+        
+        The master has full access to the slave's effector functions. slaves might expect the master to regularly refresh its commands.
+        
+        Mapping is no more allowed in this state, nor communication setup via registers.
+    */
     Operational = 8,
 }
 
@@ -179,9 +210,13 @@ pub enum AlState {
 #[bitsize(4)]
 #[derive(FromBits, DebugBits, Copy, Clone, Eq, PartialEq, Default)]
 pub struct AlMixedState {
+    /// one slave at least is in [AlState::Init]
 	pub init: bool,
+	/// one slave at least is in [AlState::PreOperational]
 	pub pre_operational: bool,
+	/// one slave at least is in [AlState::SafeOperational]
 	pub safe_operational: bool,
+	/// one slave at least is in [AlState::Operational]
 	pub operational: bool,
 }