Add docs for Int#downto

[yb66]

Update the iterator's related var name for consistency.

Did this because it only had bare signature for docs, and the to argument reads badly.

[straight-shoota]

Could you leave the parameter renaming out of this PR and just add the docs for now? I think that change might need some more discussion first.

[HertzDevil]

You can probably make to an external parameter name and limit the internal one to get the best of both worlds.

[yb66]

The last commit doesn't touch the code but I think it highlights why I feel the name change is better. Compare this:

Get an iterator for counting down from self to to

with this:

Get an iterator for counting down from self to limit

Read it out loud and it's really obvious (to my ear).

You can probably make to an external parameter name and limit the internal one to get the best of both worlds.

Method arguments gives the 2nd reason for using named parameters as…

The second use case is making a method parameter more readable inside a method body

but I'm more concerned with how the documentation reads, I'd rather that limit were the external argument.

From the issue

It's not a huge improvement

Perhaps I'm bikeshedding but my view is that code can be made to sound more like English but will always hit a limit somewhere and read like code (that's why it's called code, after all) but the documentation is English and thus any possibility to make it flow better is a win.

This should also be discussed together with Int#upto

Agreed. How about we keep this docs only, I'll push up docs only for upto as I now notice that has no docs, and that'll close this and the linked issue and I'll open a new one to keep the discussion in one place?

I just noticed that trailing semicolon, I'll fix that now too.

[HertzDevil]

But giving different external and internal parameter names doesn't imply that the docs must use the former. For instance, Steppable does this:

def step(*, to limit = nil, by step, exclusive : Bool = false, &) : Nil
Iterates from self to limit incrementing by the amount of step on each iteration. If exclusive is true, limit is excluded from the iteration.

[yb66]

I would always prefer renaming local vars over changing an API (changing a message signature). The scope of the instance vars is limited by being part of a very short interface, so it's also not a dangerous change IMO.

I now see that the current naming convention extends throughout the file and I'm getting confused with my own "fixup" commits so I'll stick to add the docs only and leave the code for another day.

[sdogruyol]

Thank you @yb66 👍