Hover Definitions for Ruby Keywords

[jamesmengo]

Set up the tooltips

Add tooltips to these keywords. The markdown files should have the description below and a newbie-friendly description.

Try to avoid having tooltips which are over-zealous (e.g. DefNode will work on any keyword within a method definition).

Tooltips

Beta Give feedback

1. __ENCODING__ - The script encoding of the current file.
2. __LINE__ - The line number of this keyword in the current file.
3. __FILE__ - The path to the current file.
4. BEGIN - Runs before any other code in the current file.
5. END - Runs after any other code in the current file.
6. alias - Creates an alias between two methods (and other things).
7. and - Short-circuit Boolean and with lower precedence than &&.
8. begin - Starts an exception handling block.
9. break - Leaves a block early.
10. case - Starts a case expression.
11. class - Creates or opens a class.
12. def - Defines a method.
13. defined? - Returns a string describing its argument.
14. do - Starts a block.
15. else - The unhandled condition in case, if and unless expressions.
16. elsif - An alternate condition for an if expression.
17. end - The end of a syntax block. Used by classes, modules, methods, exception handling and control expressions.
18. ensure - Starts a section of code that is always run when an exception is raised.
19. false - Boolean false.
20. for - A loop that is similar to using the each method.
21. if - Used for if and modifier if expressions.
22. in - Used to separate the iterable object and iterator variable in a for loop.
23. module - Creates or opens a module.
24. next - Skips the rest of the block.
25. nil - A false value usually indicating “no value” or “unknown”.
26. not - Inverts the following boolean expression. Has a lower precedence than !.
27. or - Boolean or with lower precedence than ||.
28. redo - Restarts execution in the current block.
29. rescue - Starts an exception section of code in a begin block.
30. retry - Retries an exception block.
31. return - Exits a method.
32. self - The object the current method is attached to.
33. super - Calls the current method in a superclass.
34. then - Indicates the end of conditional blocks in control structures.
35. true - Boolean true.
36. undef - Prevents a class or module from responding to a method call.
37. unless - Used for unless and modifier unless expressions.
38. until - Creates a loop that executes until the condition is true.
39. when - A condition in a case expression.
40. while - Creates a loop that executes while the condition is true.
41. yield - Starts execution of the block sent to the current method.

Write long-form documentation

Write newbie-friendly documentation in .md form for each of the following keywords. Once written, link to it from the tooltip. The link should open the markdown file locally in the editor.

Please see the north star comment from @vinistock below:

Expand thoughts on newbie-friendly documentation

I would expand on certain things and try to be super exhaustive with all aspects of the language. For example, in the methods documentation, what is a method?
In the modules documentation, we could explain that they are Ruby's way of supporting multiple inheritance, since it does not allow for more than on parent class. We should also mention the differences between prepending, including or extending a module

The goal of these docs is to make someone who is new to Ruby (or new to programming altogether) be able to gather a better understanding of how Ruby works from inside the editor. So a good exercise is trying to put yourself into the position of a newbie. What could be confusing? What was unclear when you first started with Ruby?

Long-form docs

Beta Give feedback

1. __ENCODING__ - The script encoding of the current file.
2. __LINE__ - The line number of this keyword in the current file.
3. __FILE__ - The path to the current file.
4. BEGIN - Runs before any other code in the current file.
5. END - Runs after any other code in the current file.
6. alias - Creates an alias between two methods (and other things).
7. and - Short-circuit Boolean and with lower precedence than &&.
8. begin - Starts an exception handling block.
9. break - Leaves a block early.
10. case - Starts a case expression.
11. class - Creates or opens a class.
12. def - Defines a method.
13. defined? - Returns a string describing its argument.
14. do - Starts a block.
15. else - The unhandled condition in case, if and unless expressions.
16. elsif - An alternate condition for an if expression.
17. end - The end of a syntax block. Used by classes, modules, methods, exception handling and control expressions.
18. ensure - Starts a section of code that is always run when an exception is raised.
19. false - Boolean false.
20. for - A loop that is similar to using the each method.
21. if - Used for if and modifier if expressions.
22. in - Used to separate the iterable object and iterator variable in a for loop.
23. module - Creates or opens a module.
24. next - Skips the rest of the block.
25. nil - A false value usually indicating “no value” or “unknown”.
26. not - Inverts the following boolean expression. Has a lower precedence than !.
27. or - Boolean or with lower precedence than ||.
28. redo - Restarts execution in the current block.
29. rescue - Starts an exception section of code in a begin block.
30. retry - Retries an exception block.
31. return - Exits a method.
32. self - The object the current method is attached to.
33. super - Calls the current method in a superclass.
34. then - Indicates the end of conditional blocks in control structures.
35. true - Boolean true.
36. undef - Prevents a class or module from responding to a method call.
37. unless - Used for unless and modifier unless expressions.
38. until - Creates a loop that executes until the condition is true.
39. when - A condition in a case expression.
40. while - Creates a loop that executes while the condition is true.
41. yield - Starts execution of the block sent to the current method.

Special Cases

Beta Give feedback

1. Introduce a nicer pattern in requests/hover.rb rather than constantly adding elsif statements
2. Ensure all Prism Nodes have been included + handled

[jamesmengo]

Following branch contains starters for long-form descriptions + tooltip descriptions
https://github.com/Shopify/ruby-lsp/compare/jm/hd

[Stivaros]

I've rebased your changes into my branch, thanks!

[andyw8]

A false value usually indicating “no value” or “unknown”.

I'd suggest "falsey" rather than false.

[Stivaros]

A false value usually indicating “no value” or “unknown”.

I'd suggest "falsey" rather than false.

We are pulling these from the official docs, @andyw8. We will hopefully be improving these in our newbie-friendly extended docs, though.

Or do we know the right people to update the official docs with the improved definition?

[Stivaros]

Spoke to @vinistock and we won't document cases without a corresponding Prism::XNode. For example, the do keyword tends to belong to a CallNode in Prism rather than as a DoNode. In such cases, we will just not document it, but also ensure that hovering over do doesn't show the tooltip for a CallNode.