docs: fix 0.1.4 documentation gaps and enforce API doc hygiene

.claude/skills/update-docs.md

@@ -5,7 +5,7 @@ description: Update Zensical and Dokka documentation when adding or changing a D
 
 You are updating the DevView documentation. The docs site is built with Zensical (an MkDocs fork) and API docs are generated with Dokka. Three files must stay synchronized — missing any one means the new module silently doesn't appear in the published site.
 
-## The 3 coordinated changes
+## The 4 coordinated changes
 
 ### 1. Create or update `docs/modules/<module>.md`
 
@@ -98,6 +98,17 @@ The project accessor name follows Gradle's camelCase convention from the module'
 - `devview-myfeature` → `projects.devviewMyfeature`
 - `devview-myfeature-core` → `projects.devviewMyfeatureCore`
 
+### 4. Verify KDoc is in sync with the actual API
+
+After making doc site changes, also verify that **source-level KDoc** matches the current API:
+
+- Every public enum entry has its own KDoc block.
+- Extension properties on public types have KDoc (not just the type itself).
+- Bulleted lists in KDoc that enumerate enum entries, sections, or property names are complete — no missing items.
+- Code examples in KDoc use correct property names and types.
+
+Run `git diff <module>/api/api.txt` to see what changed in the metalava surface, then verify each changed symbol has up-to-date KDoc.
+
 ## Doc build pipeline
 
 The full pipeline (from `scripts/build_docs.sh`):
@@ -127,3 +138,4 @@ The output is in `site/`. If you don't have Python/Zensical, at minimum verify:
 | New Ktor plugin variant | New `docs/modules/<module>-ktor.md` + zensical.toml + dokka |
 | Renamed or removed public API | Update docs + check for stale examples |
 | New release | `CHANGELOG.md` auto-copies via build script |
+| Changed enum entries or extension properties | Update KDoc lists that enumerate them (e.g. Section, Module) |

.pre-commit-config.yaml

@@ -9,7 +9,7 @@ repos:
     hooks:
       - id: detekt
         name: Detekt
-        entry: bash ./gradlew detektFull -Pandroidx.baselineprofile.skipgeneration
+        entry: bash -c './gradlew detektFull -Pandroidx.baselineprofile.skipgeneration && git diff --exit-code'
         language: system
         pass_filenames: false
         verbose: true

CLAUDE.md

@@ -132,3 +132,15 @@ Library group: `com.worldline.devview`. Version and Sonatype config are in `grad
 ## Changelog
 
 `CHANGELOG.md` at the repo root is the single source of truth. `docs/changelog.md` is built from it automatically — only edit the root file.
+
+## Documentation Hygiene
+
+Any change to the public API surface (anything tracked by metalava in `<module>/api/api.txt`) **must** be accompanied by documentation updates in the same PR. Before merging, check:
+
+- **KDoc in source**: Every public class, property, function, and enum entry must have KDoc. Bulleted lists that enumerate enum entries or properties (e.g. `## Available Sections`, `## Icon Mapping`) must be kept complete.
+- **`docs/modules/<module>.md`**: Update if the module's public API changed.
+- **`docs/guides/theming.md`**: Update if colors, icons, or visual appearance APIs changed.
+- **`docs/modules/custom-modules.md`** and **`docs/guides/module-development.md`**: Update if the `Module` interface or `Section` enum changed.
+- **Code samples in docs**: Verify property names, types, and constructor signatures in Markdown code blocks match the actual API — no stale examples.
+
+When the metalava `api.txt` diff in a PR is non-empty, the PR must include corresponding doc page updates (or explicitly note why none are needed).

devview-analytics/src/commonMain/kotlin/com/worldline/devview/analytics/components/AnalyticsLogItem.kt

@@ -65,61 +65,61 @@ internal fun AnalyticsLogItem(analyticsLog: AnalyticsLog, modifier: Modifier = M
                 .fillMaxHeight()
                 .background(color = categoryColor)
         )
-    Row(
-        modifier = Modifier
-            .weight(weight = 1f)
-            .padding(start = 13.dp, end = 16.dp),
-        horizontalArrangement = Arrangement.spacedBy(space = 16.dp),
-        verticalAlignment = Alignment.CenterVertically
-    ) {
-        Column(
-            modifier = Modifier.weight(weight = 1f),
-            verticalArrangement = Arrangement.spacedBy(space = 2.dp)
+        Row(
+            modifier = Modifier
+                .weight(weight = 1f)
+                .padding(start = 13.dp, end = 16.dp),
+            horizontalArrangement = Arrangement.spacedBy(space = 16.dp),
+            verticalAlignment = Alignment.CenterVertically
         ) {
-            Text(
-                modifier = Modifier.testTag(tag = "analytics_log_tag_${analyticsLog.tag}"),
-                text = analyticsLog.tag,
-                maxLines = 1,
-                overflow = TextOverflow.Ellipsis,
-                style = MaterialTheme.typography.titleMedium.copy(
-                    fontWeight = FontWeight.Bold
+            Column(
+                modifier = Modifier.weight(weight = 1f),
+                verticalArrangement = Arrangement.spacedBy(space = 2.dp)
+            ) {
+                Text(
+                    modifier = Modifier.testTag(tag = "analytics_log_tag_${analyticsLog.tag}"),
+                    text = analyticsLog.tag,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                    style = MaterialTheme.typography.titleMedium.copy(
+                        fontWeight = FontWeight.Bold
+                    )
                 )
-            )
-            Text(
-                modifier = Modifier.testTag(
-                    tag = "analytics_log_screen_class_${analyticsLog.screenClass}"
-                ),
-                text = analyticsLog.screenClass,
-                maxLines = 1,
-                overflow = TextOverflow.Ellipsis,
-                style = MaterialTheme.typography.bodySmall,
-                color = MaterialTheme.colorScheme.onSurfaceVariant
-            )
-        }
+                Text(
+                    modifier = Modifier.testTag(
+                        tag = "analytics_log_screen_class_${analyticsLog.screenClass}"
+                    ),
+                    text = analyticsLog.screenClass,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant
+                )
+            }
 
-        Column(
-            horizontalAlignment = Alignment.End,
-            verticalArrangement = Arrangement.spacedBy(space = 4.dp)
-        ) {
-            Text(
-                modifier = Modifier.testTag(
-                    tag = "analytics_log_timestamp_${analyticsLog.formattedTimestamp}"
-                ),
-                text = analyticsLog.formattedTimestamp,
-                style = MaterialTheme.typography.bodyMedium.copy(
-                    fontWeight = FontWeight.Medium
-                ),
-                color = MaterialTheme.colorScheme.onSurface
-            )
-            CategoryChip(
-                modifier = Modifier.testTag(
-                    tag = "analytics_log_category_chip_${analyticsLog.type.category}"
-                ),
-                category = analyticsLog.type.category
-            )
+            Column(
+                horizontalAlignment = Alignment.End,
+                verticalArrangement = Arrangement.spacedBy(space = 4.dp)
+            ) {
+                Text(
+                    modifier = Modifier.testTag(
+                        tag = "analytics_log_timestamp_${analyticsLog.formattedTimestamp}"
+                    ),
+                    text = analyticsLog.formattedTimestamp,
+                    style = MaterialTheme.typography.bodyMedium.copy(
+                        fontWeight = FontWeight.Medium
+                    ),
+                    color = MaterialTheme.colorScheme.onSurface
+                )
+                CategoryChip(
+                    modifier = Modifier.testTag(
+                        tag = "analytics_log_category_chip_${analyticsLog.type.category}"
+                    ),
+                    category = analyticsLog.type.category
+                )
+            }
         }
     }
-    }
 }
 
 @Preview(locale = "en")

devview-featureflip/src/commonMain/kotlin/com/worldline/devview/featureflip/FeatureFlipScreen.kt

@@ -21,7 +21,6 @@ import androidx.compose.material.icons.rounded.Close
 import androidx.compose.material.icons.rounded.Done
 import androidx.compose.material.icons.rounded.Lightbulb
 import androidx.compose.material.icons.rounded.Search
-import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.material3.FilterChip
 import androidx.compose.material3.HorizontalDivider
 import androidx.compose.material3.Icon
@@ -43,6 +42,7 @@ import androidx.compose.runtime.toMutableStateMap
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.platform.testTag
+import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.tooling.preview.Preview
 import androidx.compose.ui.unit.Dp
 import androidx.compose.ui.unit.dp

devview-featureflip/src/commonMain/kotlin/com/worldline/devview/featureflip/components/FeatureItem.kt

@@ -102,8 +102,7 @@ internal fun FeatureItem(
                     .background(
                         color = MaterialTheme.colorScheme.surfaceContainerHigh,
                         shape = MaterialTheme.shapes.extraSmall
-                    )
-                    .padding(horizontal = 6.dp, vertical = 2.dp)
+                    ).padding(horizontal = 6.dp, vertical = 2.dp)
             ) {
                 Text(
                     modifier = Modifier.testTag(tag = "feature_type_${feature.name}"),

devview-networkmock/src/commonMain/kotlin/com/worldline/devview/networkmock/NetworkMockEndpointScreen.kt

@@ -10,19 +10,18 @@ import androidx.compose.animation.slideOutVertically
 import androidx.compose.foundation.background
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.height
 import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.lazy.LazyColumn
 import androidx.compose.foundation.lazy.itemsIndexed
-import androidx.compose.foundation.layout.Row
-import androidx.compose.foundation.layout.size
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.rounded.ArrowUpward
 import androidx.compose.material.icons.rounded.TouchApp
-import androidx.compose.ui.Alignment
 import androidx.compose.material3.CardDefaults
 import androidx.compose.material3.ElevatedCard
 import androidx.compose.material3.FabPosition
@@ -38,6 +37,7 @@ import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.tooling.preview.Preview
 import androidx.compose.ui.tooling.preview.PreviewParameter

devview-networkmock/src/commonMain/kotlin/com/worldline/devview/networkmock/NetworkMockScreen.kt

@@ -19,7 +19,6 @@ import androidx.compose.material3.Tab
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
-import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableIntStateOf
 import androidx.compose.runtime.remember
@@ -31,6 +30,7 @@ import androidx.compose.ui.tooling.preview.Preview
 import androidx.compose.ui.tooling.preview.PreviewParameter
 import androidx.compose.ui.unit.Dp
 import androidx.compose.ui.unit.dp
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import com.worldline.devview.networkmock.components.EmptyState
 import com.worldline.devview.networkmock.components.EndpointCard
 import com.worldline.devview.networkmock.components.ErrorState

devview-networkmock/src/commonMain/kotlin/com/worldline/devview/networkmock/components/EndpointCard.kt

@@ -77,8 +77,7 @@ internal fun EndpointCard(
                         .background(
                             color = MaterialTheme.colorScheme.primaryContainer,
                             shape = RoundedCornerShape(size = 4.dp)
-                        )
-                        .padding(horizontal = 6.dp, vertical = 2.dp)
+                        ).padding(horizontal = 6.dp, vertical = 2.dp)
                 ) {
                     Text(
                         modifier = Modifier.testTag(

devview-networkmock/src/commonMain/kotlin/com/worldline/devview/networkmock/components/EndpointHeaderCard.kt

@@ -55,8 +55,7 @@ internal fun EndpointHeaderCard(endpoint: EndpointUiModel, modifier: Modifier =
                             .background(
                                 color = MaterialTheme.colorScheme.primaryContainer,
                                 shape = RoundedCornerShape(size = 4.dp)
-                            )
-                            .padding(horizontal = 6.dp, vertical = 2.dp)
+                            ).padding(horizontal = 6.dp, vertical = 2.dp)
                     ) {
                         Text(
                             text = endpoint.descriptor.config.method,

devview/src/commonMain/kotlin/com/worldline/devview/DevView.kt

@@ -14,7 +14,6 @@ import androidx.compose.material3.Scaffold
 import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.material3.TopAppBar
-import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.CompositionLocalProvider
 import androidx.compose.runtime.DisposableEffect
@@ -27,8 +26,8 @@ import androidx.compose.runtime.rememberUpdatedState
 import androidx.compose.runtime.saveable.rememberSaveable
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
-import androidx.compose.ui.input.nestedscroll.nestedScroll
 import androidx.compose.ui.platform.LocalLayoutDirection
+import androidx.compose.ui.text.font.FontWeight
 import androidx.navigation3.runtime.NavKey
 import androidx.navigation3.runtime.entryProvider
 import androidx.navigation3.runtime.rememberNavBackStack