search

JuliaLang / Compat.jl

Compatibility across Julia versions
Other
145 stars 117 forks source link

Explain the compat workflow for functions #827

Closed gdalle closed 3 months ago

gdalle commented 5 months ago

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 commented 5 months ago

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 commented 5 months ago

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

gdalle commented 4 months ago

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 commented 3 months ago

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 https://github.com/JuliaLang/Compat.jl/issues/814.

martinholters commented 3 months ago

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.