docs: Add comments explaining settings/project scope bridge

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: runningcode

plugin-build/src/main/kotlin/io/sentry/android/gradle/SentrySettingsPlugin.kt

@@ -10,6 +10,8 @@ class SentrySettingsPlugin : Plugin<Settings> {
   override fun apply(settings: Settings) {
     val extension = settings.extensions.create("sentry", SentrySettingsExtension::class.java)
 
+    // Stash the extension in Gradle's ExtraPropertiesExtension so the project-level
+    // plugin can read it — settings and project scopes are otherwise isolated.
     settings.gradle.extensions
       .getByType(ExtraPropertiesExtension::class.java)
       .set(SENTRY_SETTINGS_EXTENSION_KEY, extension)

plugin-build/src/main/kotlin/io/sentry/android/gradle/extensions/SentrySettingsExtension.kt

@@ -6,6 +6,15 @@ import org.gradle.api.Action
 import org.gradle.api.model.ObjectFactory
 import org.gradle.api.provider.Property
 
+/**
+ * Settings-level extension for shared Sentry configuration across all modules.
+ *
+ * Properties here are intentionally duplicated from [SentryPluginExtension] because Gradle
+ * settings extensions and project extensions live in different scopes — a project extension
+ * cannot inherit from or reference a settings extension type at configuration time. The
+ * project-level plugin bridges the two via [SentryPluginExtension.applySettingsDefaults],
+ * which wires these values as conventions (overridable defaults) on each module's extension.
+ */
 abstract class SentrySettingsExtension @Inject constructor(objects: ObjectFactory) {
 
   /** The slug of the Sentry organization. Applied as the default for all modules. */