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

Docs generator: Respect overload order between methods #10609

Merged

Conversation

HertzDevil
Copy link
Contributor

The docs generator sorts instance method / class methods / macros by their name, but since the current sort algorithm is unstable, overloads with the same name can be indeterminately ordered. Consider, for example, the Math module between two Crystal versions:

0.35.0:

  • #acos(value : Float32), #acos(value : Float64), #acos(value)
  • #acosh(value : Float32), #acosh(value : Float64), #acosh(value)
  • #asin(value : Float32), #asin(value : Float64), #asin(value)
  • #asinh(value : Float32), #asinh(value : Float64), #asinh(value)
  • #atan(value), #atan(value : Float64), #atan(value : Float32)
  • ...

1.0.0:

  • #acos(value), #acos(value : Float64), #acos(value : Float32)
  • #acosh(value : Float32), #acosh(value : Float64), #acosh(value)
  • #asin(value : Float32), #asin(value : Float64), #asin(value)
  • #asinh(value : Float64), #asinh(value), #asinh(value : Float32)
  • #atan(value : Float32), #atan(value : Float64), #atan(value)
  • ...

Overloads of each method are internally sorted by their strictness order already, so this PR exposes that order using a custom stable sort. The result is that each of the methods above will always show the Float32 overload, then the Float64 overload, and finally the restriction-less one.

This PR does not depend on #10163 (this sort would have to be stable whether or not the standard library supports it).

@straight-shoota straight-shoota added kind:bug A bug in the code. Does not apply to documentation, specs, etc. topic:tools:docs-generator labels Apr 7, 2021
Copy link
Member

@asterite asterite left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

@asterite asterite added this to the 1.1.0 milestone Apr 8, 2021
@asterite asterite merged commit 4628079 into crystal-lang:master Apr 8, 2021
@HertzDevil HertzDevil deleted the feature/doc-method-overload-order branch April 8, 2021 13:00
makenowjust added a commit to makenowjust/crystal that referenced this pull request May 27, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind:bug A bug in the code. Does not apply to documentation, specs, etc. topic:tools:docs-generator
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants