fix: Unintuitive config documentations for ES8311

[whc2001]

Description:

This documentation updates the valid values for mic_gain option and the real use of the use_microphone option. Ideally the latter should also have its name changed but that would be a breaking change.

Related issue (if applicable): fixes #5140

Pull request in esphome with YAML changes (if applicable):

Checklist:

• I am merging into next because this is new documentation that has a matching pull-request in esphome as linked above.
  or

• I am merging into current because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.

• Link added in /components/index.rst when creating new documents for new components or cookbook.

New Component Images

If you are adding a new component to ESPHome, you can automatically generate a standardized black and white component name image for the documentation.

To generate a component image:

1. Comment on this pull request with the following command, replacing COMPONENT_NAME with your component name in UPPER_CASE format with underscores (e.g., BME280, SHT3X, DALLAS_TEMP):

   @esphomebot generate image COMPONENT_NAME
   

2. The ESPHome bot will respond with a downloadable ZIP file containing the SVG image.

3. Extract the SVG file and place it in the images/ folder of this repository.

4. Use the image in your component's index table entry in /components/index.rst.

Example: For a component called "DHT22 Temperature Sensor", use:

@esphomebot generate image DHT22

[netlify]

✅ Deploy Preview for esphome ready!

Name	Link
🔨 Latest commit	251e977
🔍 Latest deploy log	https://app.netlify.com/projects/esphome/deploys/692952e54fe9e5000874e5b5
😎 Deploy Preview	https://deploy-preview-5691--esphome.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Walkthrough

Documentation update for the ES8311 audio codec component clarifying that enabling use_microphone switches the codec from analog to PDM microphone mode, and removing MIN/MAX from valid mic_gain values as they are only enum boundary guards.

Changes

Cohort / File(s)	Summary
ES8311 documentation clarifications content/components/audio_dac/es8311.md	Updated use_microphone description to clarify PDM vs. analog microphone mode switching behavior; removed MIN and MAX from mic_gain valid values list; retained default configuration values

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

• Single documentation file with text clarifications
• Changes align with existing source code behavior verification needed
• No logic, configuration, or code structure changes

Suggested labels

current

Suggested reviewers

• jesserockz

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: fixing unintuitive documentation for the ES8311 component configuration options.
Description check	✅ Passed	The description clearly explains the documentation updates to mic_gain values and use_microphone behavior, references the related issue #5140, and notes the breaking change consideration.
Linked Issues check	✅ Passed	The PR addresses both requirements from issue #5140: removing MIN/MAX from mic_gain valid values and correcting the use_microphone documentation to clarify PDM mode behavior.
Out of Scope Changes check	✅ Passed	All changes are focused on documentation updates to the ES8311 component configuration; no unrelated or out-of-scope modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 537a345 and 251e977.

📒 Files selected for processing (1)

• content/components/audio_dac/es8311.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**

⚙️ CodeRabbit configuration file

• Do not generate or add any sequence diagrams

Files:

• content/components/audio_dac/es8311.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build

🔇 Additional comments (2)

content/components/audio_dac/es8311.md (2)

29-29: Description correctly clarifies PDM vs. analog microphone mode.

The updated description now clearly indicates that enabling use_microphone switches the codec from analog to PDM microphone input, which resolves the unintuitive naming issue from issue #5140.

---

30-30: Valid mic_gain values correctly updated to exclude boundary guards.

The enumerated values now list only the practical usable gain settings (0DB through 42DB in 6dB steps), with the MIN/MAX boundary guard values removed as specified in issue #5140.

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.