Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove mention of TwicePrecision from the docs #49665

Merged
merged 1 commit into from
May 7, 2023

Conversation

Seelengrab
Copy link
Contributor

This type is internal and should not be mentioned in the manual, since we currently have the policy of "if it's in the manual, it's API". This is not API under semver, as its own docstring says:

help?> Base.TwicePrecision
  TwicePrecision{T}(hi::T, lo::T)
  TwicePrecision{T}((num, denom))

  A number with twice the precision of T, e.g., quad-precision if T = Float64.

  │ Warning
  │
  │  TwicePrecision is an internal type used to increase the precision of floating-point ranges, and not
  │  intended for external use. If you encounter them in real code, the most likely explanation is that you
  │  are directly accessing the fields of a range. Use the function interface instead, step(r) rather than
  │  r.step

[skip ci]

@dkarrasch dkarrasch added the docs This change adds or pertains to documentation label May 6, 2023
@LilithHafner
Copy link
Member

I agree with dropping TwicePrecision from the docs, but we can keep this hint without mentioning TwicePrecision explicitly:

- In conjunction with `TwicePrecision` this can be used to implement ranges that
- are free of roundoff error.
+ When `R` and `S` are more precise than `T`, this can be used to implement ranges that 
+ are free of roundoff error.

This is how we do both Float64 ranges and Float32 ranges.

julia> typeof(1.0:2.0:12.0)
StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}

julia> typeof(1.0f0:2.0f0:12.0f0)
StepRangeLen{Float32, Float64, Float64, Int64}

@Seelengrab
Copy link
Contributor Author

I removed the sentence entirely because it reads as if the user is expected to do that, which isn't the case. We already do that for them, so why mention that implementation detail?

@LilithHafner LilithHafner merged commit 09adbe3 into JuliaLang:master May 7, 2023
@LilithHafner
Copy link
Member

Good point, thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs This change adds or pertains to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants