nvda

82fb3f12 - Document gui.message.DisplayableError in the Developer Guide (#20504)

Document gui.message.DisplayableError in the Developer Guide (#20504) Closes #16984 Summary of the issue: gui.message.DisplayableError is an exception class that pairs with an extensionPoints.Action to present user-friendly errors via a message box, letting non-GUI code report a failure without deciding how it is displayed. It was undocumented: it had no entry in the Extension Points chapter of the Developer Guide, no explanation of when it should (and shouldn't) be used, and no usage examples. Its only docstring was attached to the OnDisplayableErrorT alias, leaving the class itself effectively undocumented. Description of user facing changes: None. This is a documentation and developer-facing change only. Description of developer facing changes: The Developer Guide now has a "Displaying errors to the user" section under "Communicating with the user", describing what DisplayableError is for, when to use it and when not to, and the raise / route / handle pattern, with short examples based on the Add-on Store's real usage. The Extension Points chapter now has a gui.message entry noting that DisplayableError.OnDisplayableErrorT is an Action type that components instantiate per-use, cross-referencing the new section. DisplayableError.__init__ now carries a docstring describing the class and its intended usage, so the class is documented at the point developers are most likely to look. Description of development approach: Following the discussion on the issue, the prose lives under "Communicating with the user" (which already documents the rest of gui.message) rather than only in the Extension Points chapter, so the explanation and examples sit alongside the related message dialog API. Per @seanbudd's suggestion on the issue, the class documentation was added to the existing __init__ docstring rather than as a separate class-level docstring. The examples were derived from examining the existing Add-on Store usage: DisplayableError is raised in addonStore.install and addonStore.network, routed through gui.addonStoreGui.viewModels.store.AddonStoreVM.onDisplayableError, and handled by gui.addonStoreGui.controls.storeDialog.AddonStoreDialog. The documented pattern reflects that flow, including the core.callLater hop used to ensure handlers run on the main thread when the error may be raised on a background thread, and the option for a handler to only log (as UpdatableAddonsDialog does for the automatic add-on update check).