Add comprehensive analysis of peripheral documentation completeness

PERIPHERAL_DOCS_SUMMARY.md

@@ -0,0 +1,98 @@
+# Peripheral Documentation Completeness Report
+
+**Report Date:** 2025-11-22
+
+## Quick Stats
+
+| Category | Count | Percentage |
+|----------|-------|------------|
+| 🔴 Empty/Nearly Empty | 12 | 16.0% |
+| 🟡 Very Minimal | 27 | 36.0% |
+| 🟠 Incomplete | 25 | 33.3% |
+| ✅ Complete | 11 | 14.7% |
+| **Total** | **75** | **100%** |
+
+**64 out of 75 files (85.3%) need documentation improvements**
+
+## Critical Issues (Empty Files)
+
+These files have skeletal structure only (< 20 words):
+
+- `counter.rst` (4 words)
+- `watchdog.rst` (4 words)
+- `i2c_eeprom_target.rst` (6 words)
+- `ipm.rst` (7 words)
+- `pwm.rst` (7 words)
+- `adc.rst` (8 words)
+- `spi.rst` (8 words)
+- `pcie.rst` (9 words)
+- `audio/index.rst` (11 words)
+- `can/index.rst` (12 words)
+- `gpio.rst` (16 words)
+- `tgpio.rst` (18 words)
+
+## Action Items by Priority
+
+### 🔥 Immediate Action Required
+
+**Completely Empty Files** - Add basic overview, examples, and configuration:
+
+- `counter.rst`
+- `watchdog.rst`
+- `i2c_eeprom_target.rst`
+- `ipm.rst`
+- `pwm.rst`
+- `adc.rst`
+
+### 📝 High Priority
+
+**Minimal Content Files** - Expand with proper documentation sections:
+
+- `audio/codec.rst`
+- `audio/dmic.rst`
+- `dac.rst`
+- `psi5.rst`
+- `eeprom/api.rst`
+- `sent.rst`
+- `clock_control.rst`
+- `crc.rst`
+- `eeprom/index.rst`
+- `led.rst`
+
+### 🔧 Enhancement Needed
+
+**Incomplete Documentation** - Add missing sections (examples, configuration, etc.):
+
+**Missing Overview AND Examples:**
+- `bbram.rst`
+- `charger.rst`
+- `display/index.rst`
+- `fuel_gauge.rst`
+- `index.rst`
+
+**Missing Examples:**
+- `can/transceiver.rst`
+- `comparator.rst`
+- `coredump.rst`
+- `edac/ibecc.rst`
+- `espi.rst`
+
+## Documentation Quality Metrics
+
+- **Files with Examples:** 15/75 (20.0%)
+- **Average word count:** 225.4 words
+- **Files with Configuration info:** 48/75 (64.0%)
+
+## Best Practices Examples
+
+Well-documented files to use as templates:
+
+- `i3c.rst` (1757 words, comprehensive documentation)
+- `can/controller.rst` (1600 words, comprehensive documentation)
+- `can/shell.rst` (1471 words, comprehensive documentation)
+- `mspi.rst` (987 words, comprehensive documentation)
+- `rtc.rst` (901 words, comprehensive documentation)
+
+---
+
+**For detailed analysis, see:** `doc/peripheral_documentation_analysis.md`

doc/PERIPHERAL_DOCS_README.md

@@ -0,0 +1,88 @@
+# Peripheral Documentation Analysis
+
+This directory contains analysis reports of the peripheral documentation completeness in Zephyr.
+
+## Report Files
+
+### 1. **PERIPHERAL_DOCS_SUMMARY.md** (Root Directory)
+A concise executive summary with:
+- Quick statistics and percentages
+- Critical issues requiring immediate attention
+- Action items organized by priority
+- Documentation quality metrics
+- Best practice examples
+
+**Start here** for a quick overview of the documentation status.
+
+### 2. **peripheral_documentation_analysis.md** (This Directory)
+A comprehensive detailed analysis including:
+- Complete lists of all files in each category
+- Detailed tables with word counts, line counts, and feature indicators
+- Missing sections breakdown by file
+- Feature coverage statistics
+- Reference examples of well-documented files
+
+**Use this** for in-depth analysis and planning documentation improvements.
+
+### 3. **peripheral_docs_by_category.txt** (This Directory)
+A simple text file with all 75 peripheral documentation files organized by category:
+- 🔴 Empty or Nearly Empty (12 files)
+- 🟡 Very Minimal Content (27 files)
+- 🟠 Incomplete Documentation (25 files)
+- ✅ Complete Documentation (11 files)
+
+**Use this** for quick reference when working on specific files.
+
+## Classification Criteria
+
+### Empty/Nearly Empty
+- Less than 20 words of content
+- Only skeletal structure (headings + API reference)
+- Missing overview, examples, and configuration
+
+### Very Minimal
+- 20-100 words of content
+- Basic structure present but needs substantial expansion
+- May be missing examples and detailed explanations
+
+### Incomplete
+- 100-300 words of content
+- Has some documentation but missing key sections
+- Often lacks examples, configuration details, or overview
+
+### Complete
+- More than 300 words of content
+- Comprehensive documentation with API reference
+- Includes overview, examples, and configuration where applicable
+
+## Key Findings
+
+- **85.3%** of peripheral documentation files need improvements
+- Only **20%** of files include usage examples
+- **64%** have configuration information
+- Common gaps: practical examples, overview sections, integration guides
+
+## Recommended Actions
+
+1. **Prioritize Empty Files**: Start with the 12 files that have skeletal structure only
+2. **Add Examples**: Focus on adding practical code examples (currently only 20% coverage)
+3. **Use Templates**: Reference well-documented files like `i3c.rst`, `can/controller.rst`, and `rtc.rst`
+4. **Standardize Structure**: Ensure each peripheral doc includes:
+   - Overview explaining purpose and use cases
+   - Configuration section with Kconfig options
+   - Practical code examples
+   - API reference (most already have this)
+
+## Analysis Methodology
+
+The analysis script evaluates each RST file based on:
+- Word count (excluding RST markup)
+- Presence of key sections (Overview, API, Examples, Configuration)
+- Content line count
+- Heading structure
+
+Files are automatically categorized using these metrics to provide an objective assessment of documentation completeness.
+
+## Updating the Analysis
+
+To regenerate these reports, run the analysis script located in the repository. The reports are generated from the current state of all `.rst` files in `doc/hardware/peripherals/`.

doc/peripheral_docs_by_category.txt

@@ -0,0 +1,97 @@
+================================================================================
+PERIPHERAL DOCUMENTATION FILES BY COMPLETENESS CATEGORY
+================================================================================
+
+🔴 EMPTY OR NEARLY EMPTY (12 files)
+--------------------------------------------------------------------------------
+  adc.rst                                              8 words
+  audio/index.rst                                     11 words
+  can/index.rst                                       12 words
+  counter.rst                                          4 words
+  gpio.rst                                            16 words
+  i2c_eeprom_target.rst                                6 words
+  ipm.rst                                              7 words
+  pcie.rst                                             9 words
+  pwm.rst                                              7 words
+  spi.rst                                              8 words
+  tgpio.rst                                           18 words
+  watchdog.rst                                         4 words
+
+🟡 VERY MINIMAL CONTENT (27 files)
+--------------------------------------------------------------------------------
+  audio/codec.rst                                     23 words
+  audio/dai.rst                                       40 words
+  audio/dmic.rst                                      23 words
+  audio/i2s.rst                                       49 words
+  auxdisplay.rst                                      94 words
+  clock_control.rst                                   33 words
+  crc.rst                                             34 words
+  dac.rst                                             28 words
+  edac/index.rst                                      37 words
+  eeprom/api.rst                                      30 words
+  eeprom/index.rst                                    35 words
+  entropy.rst                                         46 words
+  flash.rst                                           87 words
+  haptics.rst                                         95 words
+  hwinfo.rst                                          76 words
+  hwspinlock.rst                                      76 words
+  led.rst                                             36 words
+  mbox.rst                                            55 words
+  mdio.rst                                            57 words
+  opamp.rst                                           59 words
+  peci.rst                                            73 words
+  ps2.rst                                             76 words
+  psi5.rst                                            28 words
+  reset.rst                                           82 words
+  sensor/triggers.rst                                 75 words
+  sent.rst                                            30 words
+  usbc_vbus.rst                                       57 words
+
+🟠 INCOMPLETE DOCUMENTATION (25 files)
+--------------------------------------------------------------------------------
+  bbram.rst                                          125 words
+  can/transceiver.rst                                189 words
+  charger.rst                                        238 words
+  comparator.rst                                     260 words
+  coredump.rst                                       104 words
+  display/index.rst                                  294 words
+  edac/ibecc.rst                                     442 words
+  espi.rst                                           112 words
+  fuel_gauge.rst                                     190 words
+  gnss.rst                                           167 words
+  i2c.rst                                            284 words
+  index.rst                                          137 words
+  regulators.rst                                     156 words
+  retained_mem.rst                                   139 words
+  sdhc.rst                                           285 words
+  sensor/attributes.rst                              161 words
+  sensor/channels.rst                                125 words
+  sensor/device_tree.rst                             150 words
+  sensor/fetch_and_get.rst                           394 words
+  sensor/power_management.rst                        194 words
+  sensor/read_and_decode.rst                         604 words
+  smbus.rst                                          271 words
+  tcpc.rst                                           237 words
+  uart.rst                                           295 words
+  video.rst                                          211 words
+
+✅ COMPLETE DOCUMENTATION (11 files)
+--------------------------------------------------------------------------------
+  bc12.rst                                            565 words
+  can/controller.rst                                 1600 words
+  can/shell.rst                                      1471 words
+  dma.rst                                             440 words
+  eeprom/shell.rst                                    458 words
+  i3c.rst                                            1757 words
+  mspi.rst                                            987 words
+  rtc.rst                                             901 words
+  sensor/index.rst                                    547 words
+  stepper.rst                                         415 words
+  w1.rst                                              457 words
+
+================================================================================
+SUMMARY
+================================================================================
+Total files: 75
+Need attention: 64 (85.3%)
+Complete: 11 (14.7%)