From 3036e852a9286b6bd6e433d7f910db318048af6d Mon Sep 17 00:00:00 2001 From: Kabiru Mwenja Date: Wed, 27 May 2026 13:22:56 +0300 Subject: [PATCH] Tighten render_mode and mail formatting helper docstrings Strip a forward-looking aside about future external surfaces in RenderMode; the invariant is that external surfaces need both absolute URLs and static rendering. Replace "in practice" with "a coupled set" to drop the soft hedge. Drop the lead "wrappers around format_text" sentence on MailFormattingHelper since the module body already shows the wrapping; the WHY (channel pinning, extension/helper name parity) is the part worth documenting. --- app/helpers/mail_formatting_helper.rb | 9 ++++----- lib/open_project/text_formatting/render_mode.rb | 9 ++++----- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/app/helpers/mail_formatting_helper.rb b/app/helpers/mail_formatting_helper.rb index abaff32f244..545da16ca2c 100644 --- a/app/helpers/mail_formatting_helper.rb +++ b/app/helpers/mail_formatting_helper.rb @@ -28,11 +28,10 @@ # See COPYRIGHT and LICENSE files for more details. #++ -# Mailer-view wrappers around {OpenProject::TextFormatting#format_text}. They -# pin the external rendering channel so mailer templates never have to -# remember the `render_mode:` / `only_path:` / `static_html:` combination — -# matching the `.html.erb` / `.text.erb` template extension to the helper name -# keeps caller intent visible at the call site. +# Pin the external rendering channel so mailer templates never have to +# remember the `render_mode:` / `only_path:` / `static_html:` combination. +# Matching the `.html.erb` / `.text.erb` extension to the helper name keeps +# caller intent visible. module MailFormattingHelper def format_mail_html(*, **) format_text(*, render_mode: :external_html, **) diff --git a/lib/open_project/text_formatting/render_mode.rb b/lib/open_project/text_formatting/render_mode.rb index 3305c629b73..fd78397b739 100644 --- a/lib/open_project/text_formatting/render_mode.rb +++ b/lib/open_project/text_formatting/render_mode.rb @@ -34,11 +34,10 @@ module OpenProject # `:external_text`) onto the primitive `only_path` / `static_html` / # `plain_text` context flags that the filter pipeline reads. # - # The collapse exists because external surfaces (mailers today; RSS, PDF, - # webhooks tomorrow) always need absolute URLs *and* static rendering for - # JS-dependent components — the two flags never travel apart in practice. - # A single mode value is the canonical API; the primitives stay available - # as per-flag escape hatches for callers that need an asymmetric mix. + # External surfaces always need absolute URLs *and* static rendering for + # JS-dependent components — the two flags are a coupled set. A single + # mode value is the canonical API; the primitives stay available as + # per-flag escape hatches for callers that need an asymmetric mix. module RenderMode DEFAULTS = { in_app_html: { only_path: true, static_html: false, plain_text: false }.freeze,