From 5b20ac0ab9767ba8ee54e22d524a03c4eab266f5 Mon Sep 17 00:00:00 2001
From: Robert Sammelson <robert@sammelson.com>
Date: Wed, 17 May 2023 22:42:45 -0400
Subject: [PATCH] Add more doc comments

---
 src/commands/mod.rs   |  4 ++++
 src/commands/types.rs |  4 ++++
 src/device/elm327.rs  |  3 +++
 src/device/mod.rs     |  5 +++++
 src/error.rs          | 12 +++++++++---
 src/lib.rs            |  5 ++++-
 6 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/src/commands/mod.rs b/src/commands/mod.rs
index 0a65e4b..20ae0dd 100644
--- a/src/commands/mod.rs
+++ b/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;
diff --git a/src/commands/types.rs b/src/commands/types.rs
index db7ad8e..3ca634a 100644
--- a/src/commands/types.rs
+++ b/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),
 }
 
diff --git a/src/device/elm327.rs b/src/device/elm327.rs
index 6e413de..98e4f90 100644
--- a/src/device/elm327.rs
+++ b/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>,
diff --git a/src/device/mod.rs b/src/device/mod.rs
index 22d160f..1f0f561 100644
--- a/src/device/mod.rs
+++ b/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),
 }
diff --git a/src/error.rs b/src/error.rs
index 3138de9..87950da 100644
--- a/src/error.rs
+++ b/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 {
diff --git a/src/lib.rs b/src/lib.rs
index b5b82be..b0b6261 100644
--- a/src/lib.rs
+++ b/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;