complex numbers should be given equal place in Julia

[udohjeremiah]

Julia is a general purpose programming language but it has a domain where it shines most and that's SCIENTIFIC COMPUTING. This is to say that inasmuch as anything is related to numbers, it should be treated equally in Julia. The Julia docs IMO assumes we only use integers and floating points a lot, so they go in length when explaining any stuff on those types and show more examples on them; but for complex numbers, it's just isn't the case (few words and fewer examples is the trend).

If someone comes into Julia building an application or package that rigorously works with complex numbers and he is reading through the docs, he won't get the best experience as there are far fewer explanations on functions working with complex numbers and also far fewer examples of how the functions are even used.

About the Pull Request:

help?> round
search: round rounding RoundUp RoundDown RoundToZero RoundingMode

  round(z::Complex[, RoundingModeReal, [RoundingModeImaginary]])
  round(z::Complex[, RoundingModeReal, [RoundingModeImaginary]]; digits=, base=10)
  round(z::Complex[, RoundingModeReal, [RoundingModeImaginary]]; sigdigits=, base=10)

For the round function:

• digits=, is invalid a keyword argument in a function definition and should be digits=0.
• sigdigits=, is also invalid as well and should be sigdigits, since no default value is intended to be provided for the sigdigits keyword anyway and the ; suffice to tell its a keyword argument.

This way it will be consistent with the floating point definition of round:

help?> round
search: round rounding RoundUp RoundDown RoundToZero RoundingMode

  round([T,] x, [r::RoundingMode])
  round(x, [r::RoundingMode]; digits::Integer=0, base = 10)
  round(x, [r::RoundingMode]; sigdigits::Integer, base = 10)

Also, it's best if a little more, say 2 or 3 more examples are provided on how the round function works with complex numbers, most importantly the rounding modes.

[dkarrasch]

Thanks for the contribution and welcome to the Julia community. Great catching the stubs in the function signatures, and nice added examples! While you're at it, maybe you could also add documentation about the keyword arguments, as taken from the real analogues:

If the `digits` keyword argument is provided, it rounds to the specified number of digits after the decimal place (or before if negative), in base `base`.

If the `sigdigits` keyword argument is provided, it rounds to the specified number of significant digits, in base `base`.

Perhaps you could also add that the default imaginary rounding mode equals the real rounding mode.

[udohjeremiah]

Thanks for the contribution and welcome to the Julia community. Great catching the stubs in the function signatures, and nice added examples! While you're at it, maybe you could also add documentation about the keyword arguments, as taken from the real analogues:

If the `digits` keyword argument is provided, it rounds to the specified number of digits after the decimal place (or before if negative), in base `base`.

If the `sigdigits` keyword argument is provided, it rounds to the specified number of significant digits, in base `base`.

Perhaps you could also add that the default imaginary rounding mode equals the real rounding mode.

Great addition, thanks. But it still confuses me why some tests are failing and the PR are only added with labels but no real look into them to being merged or not? Like is there a way this works in the Julia community that I'm not understanding?

[gbaraldi]

There are two test failures, one is the whitespace check which means there is trailing whitespace somewhere in the PR. The other is an unrelated spurious failure.

[udohjeremiah]

There are two test failures, one is the whitespace check which means there is trailing whitespace somewhere in the PR. The other is an unrelated spurious failure.

How is this solved or kinda passed through so the PR can be looked into and then merged (if possible)?

[gbaraldi]

The whitespace has to be removed, vscode has tools for that, I believe github does too.

[udohjeremiah]

The whitespace has to be removed, vscode has tools for that, I believe github does too.

Remove by me?🤦🏿‍♂️

I don't even know where it is?

[dkarrasch]

Responsible as we are in the Julia community, those who have merge rights will (usually) check if the failures are related to the changes proposed in a given PR. If they clearly aren't, PRs may get merged even though tests are failing. One reason is that some issues are hard to resolve and require more time. While those issues are worked on and fixed, we as a community don't want to create a long backlog of "harmless" PRs that would otherwise need to wait before the big issue gets addressed. People might simply loose track of which PRs have already been approved. I'm not even sure you can filter PRs according to given approval. OTOH, you don't officially see if somebody else checked the reasons for the CI failure, so somebody might check, confirm failures are unrelated and without much ado just click merge. Sometimes people comment and thereby show visibly that they took care. You as an author can help that process by checking the CI logs. You yourself know very well in which part you made changes and can help others. For instance, if you realize failures are related, leave a comment and demonstrate that you're continuing working on the PR; or ask for help for concrete issues. Any of such effort, just like the initial PR (no matter code or docs) are all much appreciated.

How is this solved or kinda passed through

Just keep pushing commits to your branch with ongoing fixes. Don't worry about squashing the commits, that can be done at the end when merging.

[dkarrasch]

I don't even know where it is?

In line 556 of the log it says:

base/complex.jl:1082 -- trailing whitespace

[udohjeremiah]

I don't even know where it is?

In line 556 of the log it says:

base/complex.jl:1082 -- trailing whitespace

I think its done

[halleysfifthinc]

I disagree that the digits and sigdigits keyword args should have the documentation repeated for the complex round docstring. From the Documentation guidelines: "Specific methods should only be documented if their behaviour differs from the more generic ones. In any case, they should not repeat the information provided elsewhere." Since the behaviour of digits and sigdigits is the same for both methods, the documentation for those kwargs should not be repeated.

[udohjeremiah]

I disagree that the digits and sigdigits keyword args should have the documentation repeated for the complex round docstring. From the Documentation guidelines: "Specific methods should only be documented if their behaviour differs from the more generic ones. In any case, they should not repeat the information provided elsewhere." Since the behaviour of digits and sigdigits is the same for both methods, the documentation for those kwargs should not be repeated.

That was what I initially thought but then @dkarrasch gave a good and valid suggestion and I thought it good to be added. Well, lets say for now it should be so and probably see what @KristofferC and maybe @ViralBShah thinks of it.

[dkarrasch]

Okay, I guess it's fair to not repeat the function of the keyword arguments, even though the real method is not quite "more generic" than the complex one.

[dkarrasch]

After the little grammar fix and the removal of the two paragraphs as discussed, this should be good to go.