Open jamesmengo opened 3 months ago
Following branch contains starters for long-form descriptions + tooltip descriptions https://github.com/Shopify/ruby-lsp/compare/jm/hd
I've rebased your changes into my branch, thanks!
A false value usually indicating “no value” or “unknown”.
I'd suggest "falsey" rather than false.
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?
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
.
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).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?