Can't find documentation for the motions that nvim-surround supports

[JL102]

I've tried a few Vim motions when doing ys{motion}{char} and it doesn't seem consistent with Vim's motions.

Firstly, the command ysiw{char} implies that iw is a motion, but I can't find anything outside Surround that uses iw. I can see by experimentation the difference in behavior, where iw gets the whole word while w just goes to the end of the word:

Old text             Command         New text
ar*gs                ysiwffunc       func(args)
ar*gs                yswffunc        arfunc(gs)

but I can't find anywhere in the docs that says it explicitly. I see in the first example that ysa is short for "you surround around", implying that to Surround, the motion a means around, instead of "append" as the normal Vim motion. This example is helpful but I can't find a table in your documentation listing all of the motions and what they mean, since they are clearly different from Vim's motions.

I tried ysi%f<function name> to surround a function call, but when I tried it, nothing happened. I eventually discovered that ys%f<function name> does do something, and I also discovered that ysiWf<function name> is more helpful, as seen below:

Old text            Command       New text
Deco*upled(Bool())  ys%fFlipped   DecoFlipped(upled(Bool()))
Deco*upled(Bool())  ysiWfFlipped  Flipped(Decoupled(Bool()))

where the second line is what I wanted. But I discovered the capital W motion by chance, not from any docs. Surround's behavior with W seems different to Vim's behavior with W so I don't understand what the difference is.
Is there a table of surround's motions that I can't find? And if not, can you make one?

[kylechui]

The motions are all built-in; for something like ysaw) it's split like ys, aw, ) for verb, motion, character. See :h text-objects for more information. Every motion is supported by nvim-surround, including ones defined by other plugins since nvim-surround makes no assumptions on where the motions are defined.

[JL102]

I see, thank you. That answers most of my questions, but I still have one: Where does the "you surround around" come from in the example? :h text-objects says that the motion a" is short for "a quote", and I see that the selecting behavior of va" is slightly different from ysa") (note that the selection starts before the space, not after the space):

Old text         Command   New text
He*llo "world!"  ysa")     Hello ("world!")
He*llo "world!"  va"       Hello| "world!"|

[kylechui]

It's not documented, but nvim-surround will trim whitespace for motion-based surrounds, since I imagine most people prefer having parentheses (or other pairs) directly around the quotes instead of off-by-one on one side. This is also done to maintain parity with vim-surround. I will mention that people usually still think about it as ys and a", for "you surround" and "around quotes", not ysa as one action.

If you do want to include whitespace, visually selecting it and hitting S will surround exactly what you selected.

[JL102]

Got it, thanks! You're definitely right that trimming whitespace being desired; I do prefer the behavior of ysa" over using a visual selection and I just wanted to understand the difference. I appreciate the explanation.