Document gui.message.DisplayableError in the Developer Guide

[danielw97]

Link to issue number:

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).

Testing strategy:

• Built the Developer Guide HTML locally and confirmed the new section and Extension Points entry render correctly, including the cross-reference anchor.
• Ran ruff check and ruff format on the changed source/gui/message.py; both pass. Ran pyright on the file: 0 errors, 0 warnings.
• No unit or system tests were added: the change is documentation plus a docstring, with no behaviour change to test.

Known issues with pull request:

None.

Code Review Checklist:

• Documentation:
  • Change log entry
  • User Documentation
  • Developer / Technical Documentation
  • Context sensitive help for GUI changes
• Testing:
  • Unit tests
  • System (end to end) tests
  • Manual testing
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers
  • Localization in other languages / culture than English
• API is compatible with existing add-ons.
• Security precautions taken.