Explain the compat workflow for functions

[gdalle]

It may be silly but I spent quite some time trying to make @compat stack([x, y]) work whereas all I needed was Compat.stack([x, y])

[martinholters]

I'm a bit confused because after using Compat, all of the following should work:

stack([x, y])
Compat.stack([x, y])
@compat stack([x, y])

That said, it may make sense to clarify that @compat is mostly for syntax changes and new functions/methods are just made available by Compat. However, your addition is inserted right before "wherever you want to use syntax that differs", but it's actually not about syntax. Maybe I'm too picky? Would appreciate others to chime in.

[gdalle]

I'm a bit confused because after using Compat, all of the following should work:

Maybe but the only thing that is mentioned on the README is the macro @compat, and since I qualify all my exports, I only did

using Compat: @compat

That said, it may make sense to clarify that @compat is mostly for syntax changes and new functions/methods are just made available by Compat.

Exactly, that's the part I had not understood.

However, your addition is inserted right before "wherever you want to use syntax that differs", but it's actually not about syntax.

I'll modify the phrasing

[martinholters]

Ok with me, but I'd really appreciate others' opinions.
(And sorry for the delay.)

[gdalle]

No worries about the delay. As for the PR, I always welcome more opinions but I feel like it is a relatively low-stakes addition to the docs, so perhaps they are not necessary for merging?

[aplavin]

Something like this would indeed be helpful! Maybe stress even stronger that Compat typically doesn't define its own functions, but engages in heavy type piracy? Add a relevant warning to README or something.

I recently spent some time to understand why Iterators.cycle([1,2,3], 5) sometimes works and sometimes doesn't. Turns out, one of my dependencies loaded Compat, and whenever I loaded that dependency this cycle() method worked – but not otherwise.
This definitely doesn't make me want to use Compat myself...

Also #814.

[martinholters]

Sorry this has fallen through the cracks. No reason not to merge - even if the current phrasing might not be perfect, this PR certainly does not make things any worse.