From 182e4fcce5fb021a90f67d72c757dd9e528b96af Mon Sep 17 00:00:00 2001
From: Vinicius Stock <vinicius.stock@shopify.com>
Date: Wed, 24 Dec 2025 14:17:46 -0300
Subject: [PATCH] Standardize ListItem markup

---
 lib/rdoc/markup/list_item.rb | 156 ++++++++++++++++-------------------
 1 file changed, 71 insertions(+), 85 deletions(-)

diff --git a/lib/rdoc/markup/list_item.rb b/lib/rdoc/markup/list_item.rb
index 68193e0de5..a5f5fcf572 100644
--- a/lib/rdoc/markup/list_item.rb
+++ b/lib/rdoc/markup/list_item.rb
@@ -1,99 +1,85 @@
 # frozen_string_literal: true
-##
-# An item within a List that contains paragraphs, headings, etc.
-#
-# For BULLET, NUMBER, LALPHA and UALPHA lists, the label will always be nil.
-# For NOTE and LABEL lists, the list label may contain:
-#
-# * a single String for a single label
-# * an Array of Strings for a list item with multiple terms
-# * nil for an extra description attached to a previously labeled list item
 
-class RDoc::Markup::ListItem
-
-  ##
-  # The label for the ListItem
-
-  attr_accessor :label
-
-  ##
-  # Parts of the ListItem
-
-  attr_reader :parts
-
-  ##
-  # Creates a new ListItem with an optional +label+ containing +parts+
-
-  def initialize label = nil, *parts
-    @label = label
-    @parts = []
-    @parts.concat parts
-  end
-
-  ##
-  # Appends +part+ to the ListItem
-
-  def <<(part)
-    @parts << part
-  end
-
-  def ==(other) # :nodoc:
-    self.class == other.class and
-      @label == other.label and
-      @parts == other.parts
-  end
-
-  ##
-  # Runs this list item and all its #parts through +visitor+
-
-  def accept(visitor)
-    visitor.accept_list_item_start self
-
-    @parts.each do |part|
-      part.accept visitor
-    end
+module RDoc
+  class Markup
+    # An item within a List that contains paragraphs, headings, etc.
+    #
+    # For BULLET, NUMBER, LALPHA and UALPHA lists, the label will always be nil.
+    # For NOTE and LABEL lists, the list label may contain:
+    #
+    # * a single String for a single label
+    # * an Array of Strings for a list item with multiple terms
+    # * nil for an extra description attached to a previously labeled list item
+    class ListItem < Element
+      # The label for the ListItem
+      #: (Array[String] | String)?
+      attr_accessor :label
+
+      # Parts of the ListItem
+      attr_reader :parts
+
+      # Creates a new ListItem with an optional +label+ containing +parts+
+      #: ((Array[String] | String)?, *Element) -> void
+      def initialize(label = nil, *parts)
+        @label = label
+        @parts = parts
+      end
 
-    visitor.accept_list_item_end self
-  end
+      # Appends +part+ to the ListItem
+      #: (Element) -> void
+      def <<(part)
+        @parts << part
+      end
 
-  ##
-  # Is the ListItem empty?
+      #: (top) -> bool
+      def ==(other) # :nodoc:
+        self.class == other.class &&
+          @label == other.label &&
+          @parts == other.parts
+      end
 
-  def empty?
-    @parts.empty?
-  end
+      # Runs this list item and all its #parts through +visitor+
+      # @override
+      #: (untyped) -> void
+      def accept(visitor)
+        visitor.accept_list_item_start(self)
+        @parts.each { |part| part.accept(visitor) }
+        visitor.accept_list_item_end(self)
+      end
 
-  ##
-  # Length of parts in the ListItem
+      # Is the ListItem empty?
+      #: () -> bool
+      def empty?
+        @parts.empty?
+      end
 
-  def length
-    @parts.length
-  end
+      # Length of parts in the ListItem
+      #: () -> Integer
+      def length
+        @parts.length
+      end
 
-  def pretty_print(q) # :nodoc:
-    q.group 2, '[item: ', ']' do
-      case @label
-      when Array then
-        q.pp @label
-        q.text ';'
-        q.breakable
-      when String then
-        q.pp @label
-        q.text ';'
-        q.breakable
+      # @override
+      #: (PP) -> void
+      def pretty_print(q) # :nodoc:
+        q.group(2, "[item: ", "]") do
+          if @label
+            q.pp(@label)
+            q.text(";")
+            q.breakable
+          end
+
+          q.seplist(@parts) do |part|
+            q.pp(part)
+          end
+        end
       end
 
-      q.seplist @parts do |part|
-        q.pp part
+      # Adds +parts+ to the ListItem
+      #: (*Element) -> void
+      def push(*parts)
+        @parts.concat(parts)
       end
     end
   end
-
-  ##
-  # Adds +parts+ to the ListItem
-
-  def push *parts
-    @parts.concat parts
-  end
-
 end