Add hover documentation for 'break' keyword (#3587)

Add hover documentation for break keyword

Author: mikeygough

lib/ruby_lsp/listeners/hover.rb

@@ -7,6 +7,7 @@ class Hover
       include Requests::Support::Common
 
       ALLOWED_TARGETS = [
+        Prism::BreakNode,
         Prism::CallNode,
         Prism::ConstantReadNode,
         Prism::ConstantWriteNode,
@@ -54,6 +55,7 @@ def initialize(response_builder, global_state, uri, node_context, dispatcher, so
 
         dispatcher.register(
           self,
+          :on_break_node_enter,
           :on_constant_read_node_enter,
           :on_constant_write_node_enter,
           :on_constant_path_node_enter,
@@ -84,6 +86,11 @@ def initialize(response_builder, global_state, uri, node_context, dispatcher, so
         )
       end
 
+      #: (Prism::BreakNode node) -> void
+      def on_break_node_enter(node)
+        handle_keyword_documentation(node.keyword)
+      end
+
       #: (Prism::StringNode node) -> void
       def on_string_node_enter(node)
         if @path && File.basename(@path) == GEMFILE_NAME

lib/ruby_lsp/static_docs.rb

@@ -14,6 +14,7 @@ module RubyLsp
 
   # A map of keyword => short documentation to be displayed on hover or completion
   KEYWORD_DOCS = {
+    "break" => "Terminates the execution of a block or loop",
     "yield" => "Invokes the passed block with the given arguments",
   }.freeze #: Hash[String, String]
 end

static_docs/break.md

@@ -0,0 +1,103 @@
+# Break
+
+In Ruby, the `break` keyword is used to exit a loop or block prematurely. Unlike `next` which skips to the next iteration, `break` terminates the loop entirely and continues with the code after the loop.
+
+```ruby
+# Basic break usage in a loop
+5.times do |i|
+  break if i == 3
+
+  puts i
+end
+# Output:
+# 0
+# 1
+# 2
+```
+
+The `break` statement can be used with any of Ruby's iteration methods or loops.
+
+```ruby
+array = [1, 2, 3, 4, 5]
+
+# Break in each iteration
+array.each do |num|
+  break if num > 3
+
+  puts "Number: #{num}"
+end
+# Output:
+# Number: 1
+# Number: 2
+# Number: 3
+
+# Break in an infinite loop
+count = 0
+loop do
+  count += 1
+  break if count >= 3
+
+  puts "Count: #{count}"
+end
+# Output:
+# Count: 1
+# Count: 2
+```
+
+## Break with a Value
+
+When used inside a block, `break` can return a value that becomes the result of the method call.
+
+```ruby
+# Break with a return value in map
+result = [1, 2, 3, 4, 5].map do |num|
+  break "Too large!" if num > 3
+
+  num * 2
+end
+puts result # Output: "Too large!"
+
+# Break with a value in find
+number = (1..10).find do |n|
+  break n if n > 5 && n.even?
+end
+puts number # Output: 6
+```
+
+## Break in Nested Loops
+
+When using `break` in nested loops, it only exits the innermost loop. To break from nested loops, you typically need to use a flag or return.
+
+```ruby
+# Break in nested iteration
+(1..3).each do |i|
+  puts "Outer: #{i}"
+
+  (1..3).each do |j|
+    break if j == 2
+
+    puts "  Inner: #{j}"
+  end
+end
+# Output:
+# Outer: 1
+#   Inner: 1
+# Outer: 2
+#   Inner: 1
+# Outer: 3
+#   Inner: 1
+
+# Breaking from nested loops with a flag
+found = false
+(1..3).each do |i|
+  (1..3).each do |j|
+    if i * j == 4
+      found = true
+      break
+    end
+  end
+  break if found
+end
+```
+
+The `break` keyword is essential for controlling loop execution and implementing early exit conditions. It's particularly useful when you've found what you're looking for and don't need to continue iterating.

test/requests/hover_expectations_test.rb

@@ -929,26 +929,44 @@ def name; end
   end
 
   def test_hover_for_keywords
-    source = <<~RUBY
-      def foo
-        yield
-      end
-    RUBY
+    test_cases = {
+      "yield" => {
+        source: <<~RUBY,
+          def foo
+            yield
+          end
+        RUBY
+        position: { line: 1, character: 2 },
+      },
+      "break" => {
+        source: <<~RUBY,
+          while true
+            break
+          end
+        RUBY
+        position: { line: 1, character: 2 },
+      },
+    }
 
-    with_server(source) do |server, uri|
-      server.process_message(
-        id: 1,
-        method: "textDocument/hover",
-        params: { textDocument: { uri: uri }, position: { character: 2, line: 1 } },
-      )
+    test_cases.each do |keyword, config|
+      with_server(config[:source]) do |server, uri|
+        server.process_message(
+          id: 1,
+          method: "textDocument/hover",
+          params: {
+            textDocument: { uri: uri },
+            position: config[:position],
+          },
+        )
 
-      contents = server.pop_response.response.contents.value
-      assert_match("```ruby\nyield\n```", contents)
-      assert_match(
-        RubyLsp::KEYWORD_DOCS["yield"], #: as !nil
-        contents,
-      )
-      assert_match("[Read more](#{RubyLsp::STATIC_DOCS_PATH}/yield.md)", contents)
+        contents = server.pop_response.response.contents.value
+        assert_match("```ruby\n#{keyword}\n```", contents)
+        assert_match(
+          RubyLsp::KEYWORD_DOCS[keyword] || "No documentation found for #{keyword}",
+          contents,
+        )
+        assert_match("[Read more](#{RubyLsp::STATIC_DOCS_PATH}/#{keyword}.md)", contents)
+      end
     end
   end