Docs.

examples/src/bin/simple.rs

@@ -5,7 +5,8 @@ use clap::Parser;
 use std::io::{Read, Write};
 use std::path::Path;
 
-use ppproto::{Config, PPPoS, PPPoSAction};
+use ppproto::pppos::{PPPoS, PPPoSAction};
+use ppproto::Config;
 use serial_port::SerialPort;
 
 #[derive(Parser)]

examples/src/bin/smoltcp.rs

@@ -19,7 +19,8 @@ use smoltcp::socket::{tcp, udp};
 use smoltcp::time::{Duration, Instant};
 use smoltcp::wire::IpCidr;
 
-use ppproto::{Config, PPPoS, PPPoSAction};
+use ppproto::pppos::{PPPoS, PPPoSAction};
+use ppproto::Config;
 use serial_port::SerialPort;
 
 #[derive(clap::Parser)]

src/lib.rs

@@ -1,4 +1,7 @@
 #![cfg_attr(not(feature = "std"), no_std)]
+#![warn(missing_docs)]
+#![allow(non_upper_case_globals)]
+#![doc = include_str!("../README.md")]
 
 // This mod MUST go first, so that the others see its macros.
 pub(crate) mod fmt;
@@ -8,8 +11,8 @@ pub mod pppos;
 mod wire;
 
 pub use ppp::{Config, Ipv4Address, Ipv4Status, Phase, Status};
-pub use pppos::{BufferFullError, PPPoS, PPPoSAction};
 
+/// Invalid state error.
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct InvalidStateError;

src/ppp/ipv4cp.rs

@@ -5,12 +5,16 @@ use num_enum::{FromPrimitive, IntoPrimitive};
 use super::option_fsm::{Protocol, Verdict};
 use crate::wire::ProtocolType;
 
+/// IPv4 address.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct Ipv4Address(pub [u8; 4]);
+
 impl Ipv4Address {
+ /// The unspecified address `0.0.0.0`.
  pub const UNSPECIFIED: Self = Self([0; 4]);
 
+ /// Return whether this address is the unspecified address `0.0.0.0`.
  pub fn is_unspecified(&self) -> bool {
  *self == Self::UNSPECIFIED
  }
@@ -64,11 +68,15 @@ impl IpOption {
  }
 }
 
+/// Status of the IPv4 connection.
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct Ipv4Status {
+ /// Our adress
  pub address: Option<Ipv4Address>,
+ /// The peer's address
  pub peer_address: Option<Ipv4Address>,
+ /// DNS servers provided by the peer.
  pub dns_servers: [Option<Ipv4Address>; 2],
 }
 

src/ppp/mod.rs

@@ -13,29 +13,41 @@ use crate::wire::{Packet, ProtocolType};
 
 pub use self::ipv4cp::{Ipv4Address, Ipv4Status};
 
+/// PPP configuration.
 pub struct Config<'a> {
+ /// Username for PAP.
  pub username: &'a [u8],
+ /// Password for PAP.
  pub password: &'a [u8],
 }
 
+/// Phase of the PPP connection.
 #[derive(Copy, Clone, Eq, PartialEq, Debug, Ord, PartialOrd)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Phase {
+ /// Dead, not connected.
  Dead,
+ /// Establishing initial connection.
  Establish,
+ /// Authenticating with e.g. PAP.
  Auth,
+ /// Negotiating network parameters, with e.g. IPv4CP
  Network,
+ /// Connection is open, all layers are setup.
  Open,
 }
 
+/// Status of the PPP connection.
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct Status {
+ /// Phase
+ pub phase: Phase,
  /// IPv4 configuration obtained from IPv4CP. None if IPv4CP is not up.
  pub ipv4: Option<Ipv4Status>,
 }
 
-pub struct PPP<'a> {
+pub(crate) struct PPP<'a> {
  phase: Phase,
  pub(crate) lcp: OptionFsm<LCP>,
  pub(crate) pap: PAP<'a>,
@@ -54,6 +66,7 @@ impl<'a> PPP<'a> {
 
  pub fn status(&self) -> Status {
  Status {
+ phase: self.phase,
  ipv4: if self.ipv4cp.state() == State::Opened {
  Some(self.ipv4cp.proto().status())
  } else {

src/pppos/frame_writer.rs

@@ -1,5 +1,6 @@
 use super::crc::crc16;
 
+/// Given buffer is too small.
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct BufferFullError;

src/pppos/mod.rs

@@ -1,3 +1,5 @@
+//! PPP over Serial
+
 mod crc;
 mod frame_reader;
 mod frame_writer;
@@ -14,19 +16,35 @@ use crate::{Config, Status};
 
 pub use self::frame_writer::BufferFullError;
 
+/// Return value from [`PPPoS::poll()`].
 pub enum PPPoSAction<B> {
+ /// No action needed to take.
  None,
+ /// An IP packet was received.
+ ///
+ /// The packet is located in `buffer[range]`, you must pass it to higher layers for processing.
+ ///
+ /// When this happens, the PPPoS gives you back ownership over the RX buffer. You must put a
+ /// buffer back with [`PPPoS::put_rx_buf`] before calling `poll()` or `consume()`.
  Received(B, Range<usize>),
+ /// PPP wants to transmit some data.
+ ///
+ /// You must transmit `tx_buf[..n]` over the serial connection.
  Transmit(usize),
 }
 
+/// Main PPPoS struct.
 pub struct PPPoS<'a, B: AsMutSlice<Element = u8>> {
  frame_reader: FrameReader,
  rx_buf: Option<B>,
  ppp: PPP<'a>,
 }
 
 impl<'a, B: AsMutSlice<Element = u8>> PPPoS<'a, B> {
+ /// Create a new PPPoS
+ ///
+ /// The PPPoS is created in phase [`Dead`](crate::Phase::Dead), i.e. not connected. You must
+ /// call [`open()`](Self::open) to get it to start connecting.
  pub fn new(config: Config<'a>) -> Self {
  Self {
  frame_reader: FrameReader::new(),
@@ -35,18 +53,30 @@ impl<'a, B: AsMutSlice<Element = u8>> PPPoS<'a, B> {
  }
  }
 
+ /// Get the status of the PPPoS connection.
  pub fn status(&self) -> Status {
  self.ppp.status()
  }
 
+ /// Start opening the PPPoS connection.
+ ///
+ /// This will kick off the PPP state machine.
+ ///
+ /// Returns an error if it's not in phase [`Dead`](crate::Phase::Dead).
  pub fn open(&mut self) -> Result<(), crate::InvalidStateError> {
  self.ppp.open()
  }
 
+ /// Get whether there's a buffer available for RXing.
  pub fn has_rx_buf(&self) -> bool {
  self.rx_buf.is_some()
  }
 
+ /// Make a buffer available for RXing.
+ ///
+ /// # Panics
+ ///
+ /// Panics if there's already a buffer (i.e. if [`has_rx_buf()`](Self::has_rx_buf) returns `true`).
  pub fn put_rx_buf(&mut self, rx_buf: B) {
  if self.rx_buf.is_some() {
  panic!("called put_rx_buf when we already have a buffer.")
@@ -57,11 +87,8 @@ impl<'a, B: AsMutSlice<Element = u8>> PPPoS<'a, B> {
 
  /// Process received data and generate data to be send.
  ///
- /// Action::Received is returned when an IP packet is received. You must then pass the packet
- /// to higher layers for processing.
- ///
- /// You must provide buffer space for data to be transmitted, and transmit the returned slice
- /// over the serial connection if Action::Transmit is returned.
+ /// The return value tells you what action to take. See [`PPPoSAction`] documentation
+ /// for details.
  pub fn poll(&mut self, tx_buf: &mut [u8]) -> PPPoSAction<B> {
  let mut w = FrameWriter::new(tx_buf);
 
@@ -107,8 +134,11 @@ impl<'a, B: AsMutSlice<Element = u8>> PPPoS<'a, B> {
 
  /// Send an IP packet.
  ///
- /// You must provide buffer space for the data to be transmitted, and transmit the returned
- /// slice over the serial connection.
+ /// You must provide enough buffer space for the data to be transmitted. This function
+ /// returns the size of the encoded packet `n`, you must transmit `tx_buf[..n]` over the
+ /// serial connection.
+ ///
+ /// Returns `BufferFullError` if `tx_buf` is too small.
  pub fn send(&mut self, pkt: &[u8], tx_buf: &mut [u8]) -> Result<usize, BufferFullError> {
  // TODO check IPv4CP is up