Add explicit mention of branch cuts to log, sqrt, angle docstrings

[mcabbott]

I realised that angle doesn't even specify that it's in -π to π.

These are all pretty standard but perhaps we should be explicit?

[inkydragon]

Pkg test failed in CI is unrealted.
The version of Pkg.jl has recently been updated (#52903), so maybe you need a rebase.

[mcabbott]

By the way, I can't seem to see test logs anymore. https://buildkite.com/julialang/julia-master/builds/32444 just shows me a blank page. Any idea why this might be, do I need permissions or to log in to something?

[inkydragon]

do I need permissions or to log in to something?

No, you don't.
The page is open for anyone to view without logging in.
Maybe it's just a network issue.

test x86_64-w64-mingw32, test x86_64-linux-gnu: relocatedepot failed

Error in testset relocatedepot:
Error During Test at /cache/build/tester-amdci4-10/julialang/julia-master/julia-168a0f7012/share/julia/test/relocatedepot.jl:98
  Got exception outside of a @test
  SystemError: opening file "/cache/build/tester-amdci4-10/julialang/julia-master/tmp/jl_uYfD1u/compiled/v1.11/Foo.ji": No such file or directory
  Stacktrace:

I passed the relocatedepot test locally (Windows), so these errors are just noise.

[mcabbott]

Thanks, I now think the problem is my end, as I can see tests in a different browser.

Maybe this PR is ready, unless anyone has complaints about the precise wording etc?

[inkydragon]

LGTM.

When the math function has a separate documentation page, we can try adding a 2D angle plot of the complex plane that that can visualize the branch cuts.

Or even 3D Riemann surface:
sqrt from WikiP: https://en.wikipedia.org/wiki/Square_root#/media/File:Riemann_surface_sqrt.svg

[inkydragon]

WikiP: https://en.wikipedia.org/wiki/Square_root#/media/File:Complex_sqrt_leaf1.jpg
sage: https://doc.sagemath.org/html/en/reference/plotting/sage/plot/complex_plot.html#codecell4

using UnicodePlots

X = repeat(collect(-20:20)', outer=(41, 1));
Y = repeat(collect(20:-1:-20), outer=(1,41));
grid = complex.(X, Y) ./ 10;
Z = sqrt.(grid);
zangle = angle.(Z);
heatmap(zangle; xfact=0.1, yfact=0.1, xoffset=-2, yoffset=-2)

[inkydragon]

WikiP: https://en.wikipedia.org/wiki/Complex_logarithm#/media/File:Complex_log_domain.svg
sage: https://doc.sagemath.org/html/en/reference/plotting/sage/plot/complex_plot.html#codecell6

using UnicodePlots

X = repeat(collect(-20:20)', outer=(41, 1));
Y = repeat(collect(20:-1:-20), outer=(1,41));
grid = complex.(X, Y) ./ 10;
Z = log.(grid);
zangle = angle.(Z);
heatmap(zangle; xfact=0.1, yfact=0.1, xoffset=-2, yoffset=-2)

[mcabbott]

I wonder if it would be better to link to Wikipedia, than to try to include such details here? I would worry a bit about ending up maintaining a whole textbook.

At present the PR is just informing people who do know of the potential issue what conventions Julia adopts.