chore: refine doc comments

chore: bump version

Cargo.toml

@@ -1,14 +1,14 @@
 [package]
 name = "wlink"
-version = "0.0.0"
+version = "0.0.1"
 edition = "2021"
 authors = ["Andelf <andelf@gmail.com>"]
 repository = "https://github.com/ch32-rs/wlink"
 documentation = "https://docs.rs/wlink"
 homepage = "https://github.com/ch32-rs/wlink"
-categories = []
+categories = ["embedded", "hardware-support", "development-tools::debugging"]
-description = "WCH-Link command link util by Rust (WIP)"
+description = "WCH-Link tool for CH32V faimily MCUs(WIP)"
-keywords = ["WCH", "CH32V"]
+keywords = ["embedded", "WCH", "CH32V", "WCH-Link"]
 readme = "README.md"
 license = "MIT/Apache-2.0"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

src/commands.rs

@@ -1,10 +1,12 @@
-// pub mod dmi;
+//! WCH-Link commands and response types
 
 use std::fmt;
 
 use crate::error::{Error, Result};
 
 pub mod control;
+
+/// Command to call the WCH-Link
 pub trait Command {
     type Response: Response;
     const COMMAND_ID: u8;
@@ -17,6 +19,7 @@ pub trait Command {
     }
 }
 
+/// Response type of a command call
 pub trait Response {
     /// parse the PAYLOAD part only
     fn from_payload(bytes: &[u8]) -> Result<Self>
@@ -172,11 +175,14 @@ impl Command for DmiOp {
     type Response = DmiOpResponse;
     const COMMAND_ID: u8 = 0x08;
     fn payload(&self) -> Vec<u8> {
+        const DMI_OP_NOP: u8 = 0;
         const DMI_OP_READ: u8 = 1;
         const DMI_OP_WRITE: u8 = 2;
         let mut bytes = vec![0x00, 0x00, 0x00, 0x00, 0x00, 0x00];
         match self {
-            DmiOp::Nop => (),
+            DmiOp::Nop => {
+                bytes[5] = DMI_OP_NOP; // :)
+            }
             DmiOp::Read { addr } => {
                 bytes[0] = *addr;
                 bytes[5] = DMI_OP_READ;

src/commands/control.rs

@@ -1,3 +1,5 @@
+//! Probe control commands.
+
 use std::fmt;
 
 use crate::{RiscvChip, WchLinkVariant};
@@ -14,9 +16,9 @@ impl Command for GetProbeInfo {
 }
 #[derive(Debug)]
 pub struct ProbeInfo {
-    major_version: u8,
+    pub major_version: u8,
-    minor_version: u8,
+    pub minor_version: u8,
-    link_variant: WchLinkVariant,
+    pub variant: WchLinkVariant,
 }
 impl Response for ProbeInfo {
     fn from_payload(bytes: &[u8]) -> Result<Self> {
@@ -26,8 +28,9 @@ impl Response for ProbeInfo {
         Ok(Self {
             major_version: bytes[0],
             minor_version: bytes[1],
-            link_variant: if bytes.len() == 4 {
+            // Only avaliable in newer version of firmware
-                WchLinkVariant::from(bytes[2])
+            variant: if bytes.len() == 4 {
+                WchLinkVariant::try_from_u8(bytes[2])?
             } else {
                 WchLinkVariant::Ch549
             },

src/lib.rs

@@ -21,13 +21,13 @@ pub enum WchLinkVariant {
 }
 
 impl WchLinkVariant {
-    pub fn from(value: u8) -> Self {
+    pub fn try_from_u8(value: u8) -> Result<Self> {
         match value {
-            1 => Self::Ch549,
+            1 => Ok(Self::Ch549),
-            2 => Self::ECh32v305,
+            2 => Ok(Self::ECh32v305),
-            3 => Self::SCh32v203,
+            3 => Ok(Self::SCh32v203),
-            4 => Self::B,
+            4 => Ok(Self::B),
-            _ => panic!("invalid WCH-Link variant {}", value),
+            _ => Err(Error::Custom(format!("Unknown WCH-Link variant {}", value))),
         }
     }
 }
@@ -43,7 +43,7 @@ impl fmt::Display for WchLinkVariant {
     }
 }
 
-/// Currently supported RISC-V chip series
+/// Currently supported RISC-V chip series/family
 #[derive(Clone, Copy, Debug)]
 #[repr(u8)]
 pub enum RiscvChip {
@@ -73,7 +73,10 @@ impl RiscvChip {
             0x06 => Ok(RiscvChip::CH32V30x),
             0x07 => Ok(RiscvChip::CH58x),
             0x09 => Ok(RiscvChip::CH32V003),
-            _ => Err(Error::Custom(format!("invalid riscvchip {}", value))),
+            _ => Err(Error::Custom(format!(
+                "Unknown riscvchip type 0x{:02x}",
+                value
+            ))),
         }
     }
 }

src/main.rs

@@ -9,17 +9,16 @@ fn main() -> Result<()> {
     let mut link = WchLink::open_nth(0)?;
 
     let resp = link.send_command(commands::control::GetProbeInfo)?;
-
+    println!("probe info: {:?}", resp);
-    println!("=> {:?}", resp);
 
     let r = link.send_command(commands::control::AttachChip)?;
-    println!("=> {:?}", r);
+    println!("chip info: {:?}", r);
 
     let protected = link.send_command(commands::GetChipProtected)?;
     println!("protected => {:?}", protected);
 
-    let uid = link.send_command(commands::GetChipId);
+    let uid = link.send_command(commands::GetChipId)?;
-    println!("=> {}", uid);
+    println!("UID => {}", uid);
 
     // read csr
     link.send_command(DmiOp::write(0x10, 0x80000001))?;
@@ -32,7 +31,7 @@ fn main() -> Result<()> {
     println!("marchid => {:08x}", marchid.data);
     let marchid = marchid.data;
     println!(
-        "{}{}{}-{}{}{}",
+        "Parsed marchid: {}{}{}-{}{}{}",
         (((marchid >> 26) & 0x1F) + 64) as u8 as char,
         (((marchid >> 21) & 0x1F) + 64) as u8 as char,
         (((marchid >> 16) & 0x1F) + 64) as u8 as char,

src/transport.rs

@@ -1,3 +1,5 @@
+//! USB transport of WCH-Link
+
 use std::time::Duration;
 
 use rusb::{DeviceHandle, UsbContext};
@@ -7,7 +9,8 @@ use crate::{
     error::{Error, Result},
 };
 
-const USB_TIMEOUT_MS: u64 = 5000;
+const VENDOR_ID: u16 = 0x1a86;
+const PRODUCT_ID: u16 = 0x8010;
 
 const ENDPOINT_OUT: u8 = 0x01;
 const ENDPOINT_IN: u8 = 0x81;
@@ -16,9 +19,7 @@ const RAW_ENDPOINT_OUT: u8 = 0x02;
 const RAW_ENDPOINT_IN: u8 = 0x82;
 
 //  1a86:8010 1a86 WCH-Link  Serial: 0001A0000000
-
+const USB_TIMEOUT_MS: u64 = 5000;
-const VENDOR_ID: u16 = 0x1a86;
-const PRODUCT_ID: u16 = 0x8010;
 
 #[derive(Debug)]
 pub struct WchLink {