Add hover documentation for 'break'

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,
@@ -55,6 +56,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,
@@ -251,6 +253,11 @@ def on_class_variable_write_node_enter(node)
         handle_class_variable_hover(node.name.to_s)
       end
 
+      #: (Prism::BreakNode node) -> void
+      def on_break_node_enter(node)
+        handle_keyword_documentation(node.keyword)
+      end
+
       private
 
       #: ((Prism::InterpolatedStringNode | Prism::StringNode) node) -> void

lib/ruby_lsp/static_docs.rb

@@ -16,5 +16,6 @@ module RubyLsp
   KEYWORD_DOCS = {
     "yield" => "Invokes the passed block with the given arguments",
     "case" => "Starts a case expression for pattern matching or multiple condition checking",
+    "break" => "Terminates the execution of a block, loop, or method",
   }.freeze #: Hash[String, String]
 end

static_docs/break.md

@@ -0,0 +1,96 @@
+# 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  # Exit loop when i reaches 3
+  puts i
+end
+# Output:
+# 0
+# 1
+# 2
+```
+
+The `break` statement can be used with any of Ruby's iteration methods or loops.
+
+```ruby
+# Using break with different types of loops
+array = [1, 2, 3, 4, 5]
+
+# With each
+array.each do |num|
+  break if num > 3  # Stop when number exceeds 3
+  puts "Number: #{num}"
+end
+# Output:
+# Number: 1
+# Number: 2
+# Number: 3
+
+# With while loop
+i = 0
+while true  # Infinite loop
+  i += 1
+  break if i >= 5  # Exit condition
+  puts "Count: #{i}"
+end
+```
+
+## Break with a Value
+
+When used inside a block, `break` can return a value that becomes the result of the method call.
+
+```ruby
+# Using break with a return value
+result = [1, 2, 3, 4, 5].map do |num|
+  break "Too large!" if num > 3
+  num * 2
+end
+puts result  # Output: "Too large!"
+
+# Break in find method
+number = (1..100).find do |n|
+  break n if n > 50 && n.even?
+end
+puts number  # Output: 52
+```
+
+## Break in Nested Loops
+
+When using `break` in nested loops, it only exits the innermost loop unless explicitly used with a label (not commonly used in Ruby).
+
+```ruby
+# Break in nested iteration
+result = (1..3).each do |i|
+  puts "Outer loop: #{i}"
+  
+  (1..3).each do |j|
+    break if j == 2  # Only breaks inner loop
+    puts "  Inner loop: #{j}"
+  end
+end
+# Output:
+# Outer loop: 1
+#   Inner loop: 1
+# Outer loop: 2
+#   Inner loop: 1
+# Outer loop: 3
+#   Inner loop: 1
+
+# Breaking from nested loops using 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.