i would just inline the see also in all these places. using a macro means people browsing the source can't easily see what you're trying to inline, and if you ever want to use the macros somewhere that already has a "see also" you'll need to find another solution.

that doesn't really help me understand what it is, or why it has multiple colors, etc. would it be possible to describe it in more detail, or maybe generate screenshots showing it (in assets-for-api-docs) and pointing to those?

The audience here is people who have never used iOS. They probably need to know all the various modes it can be in, the various properties that can be used to configure it, and so on.

(the writing prompt i usually give myself is, "if someone is looking at this, that means they have a question that they're trying to answer. what is the question? what will follow-up questions be?")

Updated, let me know what you think.

This is the title of the image, but what we're supposed to provide in the alternative text is a replacement for the image, for someone who can't see it.

I think in this case what I would recommend is to not have any alternative text and just describe the image so that everyone can see the description. Something like, "when the user long-presses the space bar, they are able to drag the cursor to an arbitrary position. The floating cursor snaps to lines as the user moves it vertically, but does not snap to positions between characters horizontally. The floating cursor renders over the text field, while a faint shadow of the cursor is rendered in the text field in the location between characters where the cursor will drop into when released. The shadow cursor is a faint vertical bar with a blob at its bottom, while the floating cursor has the same appearance as a normal cursor (a blue vertical bar)."

looks like you call it a placeholder cursor rather than a shadow cursor, so obviously update my terminology to be more correct. :-)

The "floating" cursor follows the user's gesture movements exactly I believe (there's no line-snapping).

I tried it again and it does sort of snap. Maybe that's not the best way to call it?

Is this in a UIKit app? I don't think Flutter does this and I don't remember UIKit doing this either. It could be new.

Also both cursors being visible when they are so close to each other is different from the behavior I remembered. Pretty sure it used to hide the gray cursor when it's too close to the blue cursor.

This is the Reminders app on an iOS 17 simulator. I see the same behavior on Messages so maybe it's a new iOS 17 thing.

nit: force touch/long press/two-finger pan also picks up the cursor so maybe:
some editable text using certain touch gestures. As an example: when the user

Good call!