Update module documentation #1763

SergioGasquez · 2024-07-05T14:16:22Z

Thank you for your contribution!

We appreciate the time and effort you've put into this pull request.
To help us review it efficiently, please ensure you've gone through the following checklist:

Submission Checklist 📝

I have updated existing examples or added new ones (if applicable).
I have used cargo xtask fmt-packages command to ensure that all changed code is formatted correctly.
My changes were added to the CHANGELOG.md in the proper section.
My changes are in accordance to the esp-rs API guidelines

Extra:

I have read the CONTRIBUTING.md guide and followed its instructions.

Pull Request Details 📖

Description

First PR for unifying the format of module documentation. Used this format:

//! # Peripheral Name (Peripheral Acronym)
//!
//! ## Overview
//! Small description of the peripheral, see ESP-IDF docs or TRM 
//! 
//! ## Configuration
//! Explain how can the peripheral be configured, and which parameters can be configured
//! 
//! ## Usage
//! Explain if we implement any external traits
//! 
//! ## Examples
//! ### Name of the Example
//! Small description of the example if needed
//! ```rust, no_run
//! ...
//! ```
//! ## Implementation State
//! Missing features...

Still a lot of modules to be updated, but this is already a big PR (sorry)

Should close #1660

Testing

Built the documentation and ran the doc-tests.

jessebraham · 2024-07-05T14:27:20Z

Thanks for this. Will probably take me a couple days to review with that many files changes, can't see myself sitting down and just powering through all that, just FYI.

esp-hal/src/soc/esp32/gpio.rs

JurajSadel

Thank you for working on this! LGTM, I left a few comments.

esp-hal/src/aes/mod.rs

JurajSadel · 2024-07-08T11:11:19Z

esp-hal/src/analog/adc/mod.rs

-//! capable of measuring analog signals from specific analog I/O pins. One or
-//! more ADC units are available, depending on the device being used.
+//! ## Overview
+//! The ADC is integrated on the chip, and is capable of measuring analog


Maybe we can leave the Analog to Digital Converter here?

JurajSadel · 2024-07-08T11:12:51Z

esp-hal/src/analog/dac.rs

-//! precise control over voltage levels using one of the onboard
-//! digital-to-analog converters (DAC).
+//! ## Overview
+//! Espressif devices usually have multiple DAC channels. Each DAC channel can


Same as above?

esp-hal/src/interrupt/mod.rs

esp-hal/src/pcnt/mod.rs

esp-hal/src/spi/mod.rs

esp-hal/src/spi/slave.rs

esp-hal/src/timer/timg.rs

esp-hal/src/twai/mod.rs

jessebraham

Couple quick comments, I'm a little over half done reviewing and looks quite good so far. Will try to wrap this up later today or tomorrow morning.

esp-hal/src/interrupt/xtensa.rs

esp-hal/src/dma/mod.rs

jessebraham

Just a few more little things (sorry!) and then I think this is probably good to go.

esp-hal/src/rtc_cntl/sleep/mod.rs

esp-hal/src/interrupt/mod.rs

esp-hal/src/soc/esp32s2/gpio.rs

esp-hal/src/soc/esp32s3/gpio.rs

Co-authored-by: Juraj Sadel <jurajsadel@gmail.com>

Co-authored-by: Jesse Braham <jessebraham@users.noreply.github.com>

jessebraham

Thanks, LGTM!

JurajSadel

LGTM, thanks!

SergioGasquez added the skip-changelog No changelog modification needed label Jul 5, 2024

jessebraham reviewed Jul 5, 2024

View reviewed changes

esp-hal/src/soc/esp32/gpio.rs Outdated Show resolved Hide resolved

JurajSadel reviewed Jul 8, 2024

View reviewed changes

jessebraham requested changes Jul 8, 2024

View reviewed changes

esp-hal/src/interrupt/xtensa.rs Outdated Show resolved Hide resolved

esp-hal/src/dma/mod.rs Outdated Show resolved Hide resolved

SergioGasquez linked an issue Jul 9, 2024 that may be closed by this pull request

Improve module level documentation for GPIO #1660

Closed

SergioGasquez force-pushed the feature/documentation branch from 006cb38 to eac550d Compare July 9, 2024 12:54

jessebraham requested changes Jul 9, 2024

View reviewed changes

esp-hal/src/rtc_cntl/sleep/mod.rs Outdated Show resolved Hide resolved

esp-hal/src/interrupt/mod.rs Outdated Show resolved Hide resolved

esp-hal/src/soc/esp32s2/gpio.rs Outdated Show resolved Hide resolved

esp-hal/src/soc/esp32s3/gpio.rs Outdated Show resolved Hide resolved

SergioGasquez added 22 commits July 9, 2024 17:21

docs: Update GPIO docs

58ab8af

docs: Update other GPIO modules docs

2d1c650

docs: Update AES mod documentation

451cef2

docs: Update Analog and ADC mod documentation

fdc4020

docs: Update DAC mod documentation

40334ee

docs: Update lib docs

a232bae

docs: Update clock mod documentation

1d02747

docs: Update dma mod documentation

cc04aaa

docs: Update interrupt mod documentation

450b853

docs: Update lcd_cam mod documentation

93eb3ce

docs: Update ledc mod documentation

2edf230

docs: Update mcpwm mod documentation

50abd34

docs: Update pcnt mod documentation

86c845a

docs: Update rom mod documentation

634b452

docs: Update rsa mod documentation

beed589

docs: Update rtc_cntl mod documentation

4003dbe

docs: Update spi mod documentation

5e87283

docs: Update timer mod documentation

db7dc22

docs: Update twai mod documentation

a16c620

docs: Format headers

7182716

style: Fix fmt

08a325b

refactor: Change visibility instead of hidding docs

ba57b42

SergioGasquez and others added 11 commits July 9, 2024 17:21

style: Fix header

269e962

Fix typo

1984ece

Co-authored-by: Juraj Sadel <jurajsadel@gmail.com>

Fix typo

bf4526b

Co-authored-by: Juraj Sadel <jurajsadel@gmail.com>

Fix typo

b6c24b2

Co-authored-by: Juraj Sadel <jurajsadel@gmail.com>

Fix typo

48b550b

Co-authored-by: Juraj Sadel <jurajsadel@gmail.com>

Fix typo

7cd694e

Co-authored-by: Juraj Sadel <jurajsadel@gmail.com>

docs: Add tracking issue

41f2c20

docs: Remove architecture and simplify sentence

b04ada1

fix: Update visibilities remove hidden docs

47c29e8

Fix type

a368e50

Co-authored-by: Jesse Braham <jessebraham@users.noreply.github.com>

docs: Improve wording

cd66b10

Co-authored-by: Jesse Braham <jessebraham@users.noreply.github.com>

SergioGasquez force-pushed the feature/documentation branch from b263685 to cd66b10 Compare July 9, 2024 15:21

jessebraham approved these changes Jul 9, 2024

View reviewed changes

SergioGasquez mentioned this pull request Jul 9, 2024

Update module documentation - Part 2 #1777

Merged

5 tasks

jessebraham enabled auto-merge July 9, 2024 15:37

JurajSadel approved these changes Jul 9, 2024

View reviewed changes

jessebraham added this pull request to the merge queue Jul 9, 2024

Merged via the queue into esp-rs:main with commit 8e0a201 Jul 9, 2024
30 checks passed

SergioGasquez deleted the feature/documentation branch July 9, 2024 18:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update module documentation #1763

Update module documentation #1763

SergioGasquez commented Jul 5, 2024 •

edited

Loading

jessebraham commented Jul 5, 2024

JurajSadel left a comment

JurajSadel Jul 8, 2024

JurajSadel Jul 8, 2024

jessebraham left a comment

jessebraham left a comment

jessebraham left a comment

JurajSadel left a comment

Update module documentation #1763

Update module documentation #1763

Conversation

SergioGasquez commented Jul 5, 2024 • edited Loading

Thank you for your contribution!

Submission Checklist 📝

Extra:

Pull Request Details 📖

Description

Testing

jessebraham commented Jul 5, 2024

JurajSadel left a comment

Choose a reason for hiding this comment

JurajSadel Jul 8, 2024

Choose a reason for hiding this comment

JurajSadel Jul 8, 2024

Choose a reason for hiding this comment

jessebraham left a comment

Choose a reason for hiding this comment

jessebraham left a comment

Choose a reason for hiding this comment

jessebraham left a comment

Choose a reason for hiding this comment

JurajSadel left a comment

Choose a reason for hiding this comment

SergioGasquez commented Jul 5, 2024 •

edited

Loading