Add more doc comments

src/commands/mod.rs

@@ -1,4 +1,8 @@
 //! High level OBD-II interface
+//!
+//! Retrieves data from the vehicle, over the OBD-II link. The interface is defined by SAE J1979,
+//! and a list of services and PIDs is available [on
+//! Wikipedia](https://en.wikipedia.org/wiki/OBD-II_PIDs). This module mostly uses service 1.
 
 mod implementation;
 use implementation::GetObd2Values;

src/commands/types.rs

@@ -24,9 +24,13 @@ pub struct DtcsInfo {
 /// An individual trouble code from an ECU
 #[derive(Debug)]
 pub enum Dtc {
+    /// Powertrain, represented with `'P'`
     Powertrain(u16),
+    /// Chassis, represented with `'C'`
     Chassis(u16),
+    /// Chassis, represented with `'B'`
     Body(u16),
+    /// Network, represented with `'U'` likely due to previously being the "unknown" category
     Network(u16),
 }
 

src/device/elm327.rs

@@ -13,6 +13,9 @@ use super::{Error, Obd2BaseDevice, Obd2Reader, Result};
 /// Commands to the device itself are indicated by sending "AT" followed by the command, while
 /// plain strings of hex data indicate OBD-II requests to be sent to the vehicle. The responses of
 /// the vehicle are echoed back as hex characters. Capitalization and spaces are always ignored.
+///
+/// [Datasheet for v1.4b](https://github.com/rsammelson/obd2/blob/master/docs/ELM327DSH.pdf), and
+/// the [source](https://www.elmelectronics.com/products/dsheets/).
 pub struct Elm327 {
     device: ftdi::Device,
     buffer: VecDeque<u8>,

src/device/mod.rs

@@ -50,10 +50,15 @@ pub trait Obd2Reader {
 /// Error type for low-level ODB-II communication issues
 #[derive(thiserror::Error, Debug)]
 pub enum Error {
+    /// An error with the underlying [FTDI device](ftdi::Device)
     #[error("FTDI error: `{0:?}`")]
     Ftdi(ftdi::Error),
+
+    /// An I/O error in a low-level [std::io] stream operation
     #[error("IO error: `{0:?}`")]
     IO(std::io::Error),
+
+    /// An OBD-II or interface device protocol error
     #[error("Communication error: `{0}`")]
     Communication(String),
 }

src/error.rs

@@ -1,17 +1,23 @@
 pub type Result<T> = std::result::Result<T, Error>;
 
+/// An error with OBD-II communication
 #[derive(thiserror::Error, Debug)]
 pub enum Error {
+    /// An error occured in the [Odb2BaseDevice](crate::device::Obd2BaseDevice)
     #[error("Device error: `{0:?}`")]
     Device(DeviceError),
-    #[error("Other OBD2 error: `{0}`")]
+
-    Other(String),
+    /// Some part of the response (described by the `&str`) was not the expected length
     #[error("Incorrect length (`{0}`): expected `{1}`, got `{2}`")]
     IncorrectResponseLength(&'static str, usize, usize),
+
+    /// Another error occurred
+    #[error("Other OBD2 error: `{0}`")]
+    Other(String),
 }
 
 #[derive(Debug)]
-pub struct DeviceError(super::device::Error);
+pub struct DeviceError(crate::device::Error);
 
 impl From<super::device::Error> for Error {
     fn from(e: super::device::Error) -> Self {

src/lib.rs

@@ -1,6 +1,8 @@
 //! Crate for communicating with OBD-II (on-board diagnostics) interfaces on cars
 //!
-//! The high-level data retrieval functions can be found in [commands::Obd2DataRetrieval].
+//! Currently only the ELM327 is supported (many cheap USB to OBD-II devices you can buy online are
+//! compatible with the ELM327). The high-level data retrieval functions can be found in
+//! [commands::Obd2DataRetrieval].
 //!
 //! # Usage
 //! ```
@@ -14,6 +16,7 @@
 //! ```
 
 #![forbid(unsafe_code)]
+#![warn(missing_docs)]
 
 pub mod commands;