Add remarks and examples to Microsoft.Windows.System.Power API docs

[GrantMeStrength]

Questions for SME reviewers

The following questions came up during authoring. Accurate answers would directly improve the docs — and are especially important for AI coding assistants (e.g. GitHub Copilot) that use API reference to generate code.

PowerManager properties

1. RemainingDischargeTime when on AC — What does RemainingDischargeTime return when the device is plugged in? TimeSpan.Zero? TimeSpan.MaxValue? Should we document the behavior?
2. RemainingChargePercent on desktop — What does RemainingChargePercent return on a desktop PC with no battery? 0? -1? Should we document the no-battery case?
3. PowerSupplyStatus.Inadequate threshold — Is there a documented wattage or percentage threshold that distinguishes Inadequate from Adequate, or is this OEM-defined?
4. EffectivePowerMode vs EffectivePowerMode2 — Why do both exist? Is EffectivePowerMode (async) deprecated in favor of EffectivePowerMode2 (sync)? Should we guide developers toward one?

Events

5. Event thread/context — Are PowerManager events raised on the UI thread, a background thread, or the thread that subscribed? This affects whether developers need to marshal to the UI thread.
6. SystemIdleStatusChanged — The existing remark says "Raised when the system is busy," which seems backwards. Is this raised when the system transitions to idle, from idle, or both?
7. Event unsubscription — Do apps need to explicitly unsubscribe from PowerManager events on shutdown, or does the static event handler handle cleanup?

Enums

8. BatteryStatus.Idle vs Charging — Is Idle specifically "fully charged and on AC" or can it also mean "on battery but not discharging" (e.g., conservation mode)?
9. EffectivePowerMode ordering — We described the values as ordered from lowest to highest power. Is this ordering guaranteed/contractual, or just the current layout?
10. SystemSuspendStatus.AutoResume triggers — What specific conditions cause AutoResume vs ManualResume? Wake timers? Network wake? Power button?

General

11. Win32 parity — Are there any behavioral differences between these WinRT APIs and the underlying Win32 power setting GUIDs they wrap?
12. Packaged vs unpackaged — Are there any capabilities or restrictions that differ between packaged (MSIX) and unpackaged apps for these APIs?

---

Summary

Adds remarks to 12 files in Microsoft.Windows.System.Power (namespace overview, PowerManager class, 6 properties, 4 enums). Adds a C# code example to the PowerManager class showing battery status checks and event subscriptions.

Changes

• Namespace overview (microsoft_windows_system_power.md): Usage guidance and common scenarios
• PowerManager class (powermanager.md): Static class guidance, packaged/unpackaged note, full C# example with battery check + event subscription + energy saver handling
• 6 property files: BatteryStatus, EffectivePowerMode, EffectivePowerMode2, PowerSupplyStatus, RemainingDischargeTime, SystemSuspendStatus — usage guidance, related event/enum cross-references
• 4 enum files: BatteryStatus, EffectivePowerMode, PowerSupplyStatus, SystemSuspendStatus — contextual remarks explaining when/how each value applies

Motivation

OGF quality scan identified 22/32 files in this namespace with empty or minimal remarks. This PR fills the highest-impact gaps. All claims are derived from the API signatures, enum field descriptions, and existing remarks in sibling files — no unverifiable claims.

[Copilot]

Pull request overview

This PR enhances the API reference documentation for Microsoft.Windows.System.Power by adding practical remarks and a C# example to help developers correctly interpret power-related properties/events and related enums.

Changes:

• Expanded remarks across the namespace overview, PowerManager class, several PowerManager properties, and multiple enums to provide usage guidance and cross-references.
• Added a C# example to PowerManager showing power source checks and event subscriptions.
• Added contextual explanations for enum values (for example, EffectivePowerMode, PowerSupplyStatus, SystemSuspendStatus, BatteryStatus).

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
microsoft.windows.system.power/microsoft_windows_system_power.md	Adds namespace-level usage guidance and common scenarios.
microsoft.windows.system.power/powermanager.md	Adds static-class guidance, packaged/unpackaged note, and a C# usage example.
microsoft.windows.system.power/powermanager_batterystatus.md	Adds remarks describing how to interpret BatteryStatus and subscribe to changes.
microsoft.windows.system.power/powermanager_effectivepowermode.md	Adds remarks describing EffectivePowerMode usage and a sync alternative.
microsoft.windows.system.power/powermanager_effectivepowermode2.md	Adds remarks describing the synchronous EffectivePowerMode2 property and event subscription.
microsoft.windows.system.power/powermanager_powersupplystatus.md	Adds remarks describing PowerSupplyStatus and subscribing to changes.
microsoft.windows.system.power/powermanager_remainingdischargetime.md	Adds remarks describing RemainingDischargeTime meaning and relevant event.
microsoft.windows.system.power/powermanager_systemsuspendstatus.md	Adds remarks on using SystemSuspendStatus with its event for suspend/resume handling.
microsoft.windows.system.power/batterystatus.md	Adds enum remarks to interpret BatteryStatus values.
microsoft.windows.system.power/effectivepowermode.md	Adds enum remarks explaining EffectivePowerMode usage and intended interpretation.
microsoft.windows.system.power/powersupplystatus.md	Adds enum remarks to interpret PowerSupplyStatus values.
microsoft.windows.system.power/systemsuspendstatus.md	Adds enum remarks explaining SystemSuspendStatus and resume distinctions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.