Document enum-flag converter requirement

[kirich1409]

Summary

Consumers who declare enum(...) flags in the featured { } DSL hit a silent crash
at first read/write on Android/JVM, and have no path forward on iOS, because neither
requirement was documented. This PR adds KDoc and a README section to surface both.

• FlagContainer.enum KDoc — explains that every storage-backed local provider
  (DataStoreConfigValueProvider, JavaPreferencesConfigValueProvider,
  SharedPreferencesProviderConfig) requires registerConverter(enumConverter<T>())
  before the first use; includes minimal Gradle DSL + runtime wiring examples.
• enumConverter KDoc — appends a "Compatible providers" section listing which
  providers accept the converter, notes Firebase is automatic, and surfaces the
  NSUserDefaults caveat.
• featured-gradle-plugin/README.md (new, minimal) — "Enum flags" section with a
  quick-reference table and the iOS workaround note.

No runtime code, type signatures, or ABI changed — checkLegacyAbi passes clean.

Files touched

• core/src/commonMain/kotlin/dev/androidbroadcast/featured/TypeConverter.kt
• featured-gradle-plugin/src/main/kotlin/dev/androidbroadcast/featured/gradle/FlagContainer.kt
• featured-gradle-plugin/README.md (new)

Related branches

Part of a documentation + fix trio for the enum-flag gap:

• fix/configvalues-observe-catch — runtime fix
• fix/sample-enum-converter — sample app wiring fix
• docs/enum-flag-registerconverter — this PR

Test plan

• ./gradlew :featured-gradle-plugin:compileKotlin passes
• ./gradlew :core:compileKotlinMetadata passes
• ./gradlew :core:checkLegacyAbi passes (no ABI diff)
• ./gradlew spotlessCheck passes
• git diff shows only KDoc and markdown lines changed

🤖 Generated with Claude Code

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[Copilot]

Pull request overview

Documentation-only PR that surfaces the previously undocumented runtime requirement to register an enumConverter on storage-backed local providers when using enum(...) flags declared via the featured { } Gradle DSL, and notes the missing iOS support. No runtime/ABI changes.

Changes:

• Expanded KDoc on FlagContainer.enum(...) describing the converter requirement, affected providers, Firebase auto-handling, the iOS caveat, and adds Gradle DSL + runtime wiring examples.
• Added a "Compatible providers" section to enumConverter KDoc in core/.../TypeConverter.kt.
• New featured-gradle-plugin/README.md with an "Enum flags" section, provider/registration table, and iOS caveat.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
core/src/commonMain/kotlin/dev/androidbroadcast/featured/TypeConverter.kt	Adds compatible-providers and iOS-caveat notes to enumConverter KDoc.
featured-gradle-plugin/src/main/kotlin/dev/androidbroadcast/featured/gradle/FlagContainer.kt	Expands enum(...) KDoc with converter requirement, affected providers, and examples.
featured-gradle-plugin/README.md	New plugin README documenting enum-flag wiring and iOS workaround.

[cubic-dev-ai]

1 issue found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="featured-gradle-plugin/src/main/kotlin/dev/androidbroadcast/featured/gradle/FlagContainer.kt">

<violation number="1" location="featured-gradle-plugin/src/main/kotlin/dev/androidbroadcast/featured/gradle/FlagContainer.kt:94">
P3: Unresolvable KDoc link: `[enumConverter]` is defined in the `core` module which is not a dependency of `featured-gradle-plugin`. This will produce a broken link or KDoc warning. Use a fully-qualified reference or backtick-quoted text instead.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P3: Unresolvable KDoc link: [enumConverter] is defined in the core module which is not a dependency of featured-gradle-plugin. This will produce a broken link or KDoc warning. Use a fully-qualified reference or backtick-quoted text instead.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At featured-gradle-plugin/src/main/kotlin/dev/androidbroadcast/featured/gradle/FlagContainer.kt, line 94:

<comment>Unresolvable KDoc link: `[enumConverter]` is defined in the `core` module which is not a dependency of `featured-gradle-plugin`. This will produce a broken link or KDoc warning. Use a fully-qualified reference or backtick-quoted text instead.</comment>

<file context>
@@ -84,8 +84,49 @@ public class FlagContainer {
+     * ## Runtime converter requirement (Android / JVM)
+     *
+     * Storage-backed local providers serialize values as strings and require an explicit
+     * [enumConverter] registration before the first read or write of this flag. Without it the
+     * provider throws [IllegalArgumentException] synchronously. Affected providers:
+     *
</file context>