---
# System prepended metadata

title: Module-level documentation template discussion
tags: [documentation, esp-hal]

---

:warning: FEEL FREE TO LEAVE COMMENTS

ATM the idea is just to keep the next template for writing module-level documentation for peripherals:
- Name
- Description (Introduction)
- Example of usage/initialisation

Example: 

```
//! USB Serial JTAG peripheral driver
//! 
//! # Introduction
//! The USB Serial JTAG peripheral driver provides an interface to communicate
//! with the USB Serial/JTAG peripheral on ESP chips. It enables serial communication
//! and JTAG debugging capabilities, allowing developers to interact with the ESP chip
//! for programming, debugging, and data transfer purposes, can be also used to program
//! the SoC's flash, read program output, as well as attach a debugger to a running program.
//! 
//! # Initialization
//! ```no_run
//! let peripherals = Peripherals::take();
//! let mut system = peripherals.SYSTEM.split();
//! let clocks = ClockControl::boot_defaults(system.clock_control).freeze();
//!
//! // Initialize USB Serial/JTAG peripheral
//! let mut usb_serial =
//!    UsbSerialJtag::new(peripherals.USB_DEVICE, &mut system.peripheral_clock_control);
//! ```
//!
//! # Reading
//! ```no_run
//! ```
//!
//! # Writing
//! ```no_run
//! ```
//!
```

## Comments

[JB] - Should we remove the `clocks` variable altogether, since it's never actually referenced elsewhere?
[JB] - May be nice to add some simple examples of reading/writing/other modes of use?
[JB] - Should we mention which trait(s) is/are implemented from the various `embedded-hal(-*)` packages?
