ts_headline performance note

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/16/textsearch-controls.html
Description:

My team recently ran into a performance issue that turned out to involve
ts_headline, so I've been looking at the documentation. In 12.3.4.
Highlighting Results, the last line says: "ts_headline uses the original
document, not a tsvector summary, so it can be slow and should be used with
care."

This sentence was easy for me to miss at first because it's a small line
between a long example block and the footer material. If a person needs to
use this with care, should that note be incorporated into the introduction
to the section?

Also, I see at
https://github.com/postgres/postgres/commit/d5d8a0b7e54ca09d0b5fdfc6afcb307450f33215
(discussed at
https://www.postgresql.org/message-id/6700.1478986625%40sss.pgh.pa.us) that
this section previously provided an example that became obsolete. "Used with
care" is a bit vague on its own, and future readers could benefit from a
more specific statement or a new example of how to use it with care.

Thank you very much! I appreciate the work of documentation editors.