Modernize inline code references

context/getting-started.md

@@ -12,7 +12,7 @@ $ bundle add decode
 
 ## Indexing
 
-`decode` turns your source code into a kind of database with rich access to definitions, segments and associated comments. Use {ruby Decode::Index} to build an index of your project by loading in source files:
+`decode` turns your source code into a kind of database with rich access to definitions, segments and associated comments. Use ruby:`Decode::Index` to build an index of your project by loading in source files:
 
 ~~~ ruby
 require 'decode/index'
@@ -44,11 +44,11 @@ puts definition.long_form
 
 ## Documentation
 
-The {ruby Decode::Documentation} provides rich access to the comments that preceed a definition. This includes metadata including `@parameter`, `@returns` and other tags.
+The ruby:`Decode::Documentation` provides rich access to the comments that preceed a definition. This includes metadata including `@parameter`, `@returns` and other tags.
 
 ~~~ ruby
 lines = definition.documentation.text
 puts lines
 ~~~
 
-See {ruby Decode::Comment::Node#traverse} for more details about how to consume this data.
+See ruby:`Decode::Comment::Node#traverse` for more details about how to consume this data.

context/ruby-documentation.md

@@ -22,10 +22,10 @@ This guide covers documentation practices and pragmas supported by the Decode ge
 
 #### Links and Code Formatting
 
-- Curly braces `{}`: Use curly braces to create links to other methods, classes, or modules. The Decode gem uses `@index.lookup(text)` to resolve these references.
-  - Absolute references: `{Decode::Index#lookup}` - Links to a specific method in a specific class
-  - Relative references: `{lookup}` - Links to a method in the current scope or class
-  - Class references: `{User}` - Links to a class or module
+- Language-prefixed inline code: Use ruby:`identifier` to create links to other methods, classes, or modules. The Decode gem uses `@index.lookup(text)` to resolve these references.
+  - Absolute references: ruby:`Decode::Index#lookup` - Links to a specific method in a specific class
+  - Relative references: ruby:`lookup` - Links to a method in the current scope or class
+  - Class references: ruby:`User` - Links to a class or module
 - Backticks: Use backticks for code formatting of symbols, values, method names, and technical terms that should appear in monospace font.
   - Symbols: `:admin`, `:user`, `:guest`
   - Values: `true`, `false`, `nil`
@@ -68,7 +68,7 @@ class User
 
 	# Deactivate the user account.
 	# This method sets the user's status to inactive. Use this instead of
-	# the deprecated {disable!} method. The account status can be checked
+	# the deprecated ruby:`disable!` method. The account status can be checked
 	# using `active?` or by examining the `:active` attribute.
 	# @returns [bool] Returns `true` if deactivation was successful.
 	def deactivate!
@@ -106,7 +106,7 @@ end
 Note the difference: `User` is described as a thing ("A user account..."), while `Client` is described by what it does ("An HTTP client that manages..."), and `ConnectionError` is described by when it occurs ("Raised when...").
 
 **Key formatting examples from above:**
-- `{disable!}` - Creates a link to the `disable!` method (relative reference)
+- ruby:`disable!` - Creates a link to the `disable!` method (relative reference)
 - `active?` - Formats the method name in monospace (backticks for code formatting)
 - `:active` - Formats the symbol in monospace (backticks for code formatting)
 - `true` - Formats the boolean value in monospace (backticks for code formatting)
@@ -306,7 +306,7 @@ end
 Marks methods as deprecated with migration guidance.
 
 ```ruby
-# @deprecated Use {new_method} instead.
+# @deprecated Use ruby:`new_method` instead.
 def old_method
 	# Legacy implementation
 end

guides/extract-symbols/extract.rb

@@ -4,7 +4,7 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-# This example demonstrates how to extract symbols using the index. An instance of {Decode::Index} is used for loading symbols from source code files. These symbols are available as a flat list and as a trie structure. You can look up specific symbols using a reference using {Decode::Index#lookup}.
+# This example demonstrates how to extract symbols using the index. An instance of ruby:`Decode::Index` is used for loading symbols from source code files. These symbols are available as a flat list and as a trie structure. You can look up specific symbols using a reference using ruby:`Decode::Index#lookup`.
 require_relative "../../lib/decode/index"
 
 # Firstly, construct the index:

guides/getting-started/readme.md

@@ -12,7 +12,7 @@ $ bundle add decode
 
 ## Indexing
 
-`decode` turns your source code into a kind of database with rich access to definitions, segments and associated comments. Use {ruby Decode::Index} to build an index of your project by loading in source files:
+`decode` turns your source code into a kind of database with rich access to definitions, segments and associated comments. Use ruby:`Decode::Index` to build an index of your project by loading in source files:
 
 ~~~ ruby
 require 'decode/index'
@@ -44,11 +44,11 @@ puts definition.long_form
 
 ## Documentation
 
-The {ruby Decode::Documentation} provides rich access to the comments that preceed a definition. This includes metadata including `@parameter`, `@returns` and other tags.
+The ruby:`Decode::Documentation` provides rich access to the comments that preceed a definition. This includes metadata including `@parameter`, `@returns` and other tags.
 
 ~~~ ruby
 lines = definition.documentation.text
 puts lines
 ~~~
 
-See {ruby Decode::Comment::Node#traverse} for more details about how to consume this data.
+See ruby:`Decode::Comment::Node#traverse` for more details about how to consume this data.

guides/ruby-documentation/readme.md

@@ -22,10 +22,10 @@ This guide covers documentation practices and pragmas supported by the Decode ge
 
 #### Links and Code Formatting
 
-- Curly braces `{}`: Use curly braces to create links to other methods, classes, or modules. The Decode gem uses `@index.lookup(text)` to resolve these references.
-  - Absolute references: `{Decode::Index#lookup}` - Links to a specific method in a specific class
-  - Relative references: `{lookup}` - Links to a method in the current scope or class
-  - Class references: `{User}` - Links to a class or module
+- Language-prefixed inline code: Use ruby:`identifier` to create links to other methods, classes, or modules. The Decode gem uses `@index.lookup(text)` to resolve these references.
+  - Absolute references: ruby:`Decode::Index#lookup` - Links to a specific method in a specific class
+  - Relative references: ruby:`lookup` - Links to a method in the current scope or class
+  - Class references: ruby:`User` - Links to a class or module
 - Backticks: Use backticks for code formatting of symbols, values, method names, and technical terms that should appear in monospace font.
   - Symbols: `:admin`, `:user`, `:guest`
   - Values: `true`, `false`, `nil`
@@ -68,7 +68,7 @@ class User
 
 	# Deactivate the user account.
 	# This method sets the user's status to inactive. Use this instead of
-	# the deprecated {disable!} method. The account status can be checked
+	# the deprecated ruby:`disable!` method. The account status can be checked
 	# using `active?` or by examining the `:active` attribute.
 	# @returns [bool] Returns `true` if deactivation was successful.
 	def deactivate!
@@ -106,7 +106,7 @@ end
 Note the difference: `User` is described as a thing ("A user account..."), while `Client` is described by what it does ("An HTTP client that manages..."), and `ConnectionError` is described by when it occurs ("Raised when...").
 
 **Key formatting examples from above:**
-- `{disable!}` - Creates a link to the `disable!` method (relative reference)
+- ruby:`disable!` - Creates a link to the `disable!` method (relative reference)
 - `active?` - Formats the method name in monospace (backticks for code formatting)
 - `:active` - Formats the symbol in monospace (backticks for code formatting)
 - `true` - Formats the boolean value in monospace (backticks for code formatting)
@@ -306,7 +306,7 @@ end
 Marks methods as deprecated with migration guidance.
 
 ```ruby
-# @deprecated Use {new_method} instead.
+# @deprecated Use ruby:`new_method` instead.
 def old_method
 	# Legacy implementation
 end

lib/decode/comment/node.rb

@@ -14,7 +14,7 @@ def initialize(children)
 			end
 
 			# Whether this node has any children nodes.
-			# Ignores {Text} instances.
+			# Ignores ruby:`Text` instances.
 			# @returns [bool]
 			def children?
 				@children&.any?{|child| child.is_a?(Node)} || false
@@ -75,7 +75,7 @@ def text
 				end
 			end
 
-			# Traverse the tags from this node using {each}. Invoke `descend.call(child)` to recursively traverse the specified child.
+			# Traverse the tags from this node using ruby:`each`. Invoke `descend.call(child)` to recursively traverse the specified child.
 			#
 			# @yields {|node, descend| descend.call}
 			# 	@parameter node [Node] The current node which is being traversed.

lib/decode/comment/pragma.rb

@@ -10,7 +10,7 @@ module Comment
 		# Asserts a specific property about the method signature.
 		#
 		# - `@reentrant This method is thread-safe.`
-		# - `@deprecated Please use {other_method} instead.`
+		# - ``@deprecated Please use ruby:`other_method` instead.``
 		# - `@blocking This method may block.`
 		# - `@asynchronous This method may yield.`
 		#

lib/decode/definition.rb

@@ -139,7 +139,7 @@ def long_form
 		end
 
 		# A long form which uses the qualified name if possible.
-		# Defaults to {long_form}.
+		# Defaults to ruby:`long_form`.
 		#
 		# @returns [String?]
 		def qualified_form
@@ -183,7 +183,7 @@ def nested?
 
 		# Structured access to the definitions comments.
 		#
-		# @returns [Documentation?] A {Documentation} instance if this definition has comments.
+		# @returns [Documentation?] A ruby:`Documentation` instance if this definition has comments.
 		def documentation
 			if comments = @comments and comments.any?
 				@documentation ||= Documentation.new(comments, @language)
@@ -192,7 +192,7 @@ def documentation
 
 		# The location of the definition.
 		#
-		# @returns [Location?] A {Location} instance if this definition has a location.
+		# @returns [Location?] A ruby:`Location` instance if this definition has a location.
 		def location
 			nil
 		end

lib/decode/segment.rb

@@ -30,7 +30,7 @@ def initialize(comments, language)
 		attr :language
 
 		# An interface for accsssing the documentation of the definition.
-		# @returns [Documentation?] A {Documentation} instance if this definition has comments.
+		# @returns [Documentation?] A ruby:`Documentation` instance if this definition has comments.
 		def documentation
 			if @comments&.any?
 				@documentation ||= Documentation.new(@comments, @language)

lib/decode/trie.rb

@@ -119,7 +119,7 @@ def each(path = [], &block)
 		end
 
 		# Traverse the trie starting from the specified path.
-		# See {Node#traverse} for details.
+		# See ruby:`Node#traverse` for details.
 		# @parameter path [Array(Symbol)] The starting path to traverse from.
 		# @yields {|path, node, descend| ...} Called for each node during traversal.
 		# @rbs (?Array[Symbol]) { (Array[Symbol], Node, Proc) -> void } -> void

sig/decode.rbs

@@ -47,7 +47,7 @@ module Decode
       public def initialize: (Array[Node | Text]? children) -> void
 
       # Whether this node has any children nodes.
-      # Ignores {Text} instances.
+      # Ignores ruby:`Text` instances.
       public def children?: () -> bool
 
       # Add a child node to this node.
@@ -62,7 +62,7 @@ module Decode
       # Any lines of text associated with this node.
       public def text: () -> Array[String]?
 
-      # Traverse the tags from this node using {each}. Invoke `descend.call(child)` to recursively traverse the specified child.
+      # Traverse the tags from this node using ruby:`each`. Invoke `descend.call(child)` to recursively traverse the specified child.
       public def traverse: () { (Node node, Proc descend) -> void } -> untyped
 
       # Extract text lines from Text children of this node.
@@ -99,7 +99,7 @@ module Decode
     # Asserts a specific property about the method signature.
     #
     # - `@reentrant This method is thread-safe.`
-    # - `@deprecated Please use {other_method} instead.`
+    # - ``@deprecated Please use ruby:`other_method` instead.``
     # - `@blocking This method may block.`
     # - `@asynchronous This method may yield.`
     class Pragma < Tag
@@ -302,7 +302,7 @@ module Decode
     public def long_form: () -> String?
 
     # A long form which uses the qualified name if possible.
-    # Defaults to {long_form}.
+    # Defaults to ruby:`long_form`.
     public def qualified_form: () -> String?
 
     # Whether the definition spans multiple lines.
@@ -1161,7 +1161,7 @@ module Decode
     public def each: (?Array[Symbol]) { (Array[Symbol], Array[T] | nil) -> void } -> void
 
     # Traverse the trie starting from the specified path.
-    # See {Node#traverse} for details.
+    # See ruby:`Node#traverse` for details.
     public def traverse: (?Array[Symbol]) { (Array[Symbol], Node, Proc) -> void } -> void
 
     # Represents a single node in the trie.

test/decode/comment/.fixtures/text.rb

@@ -8,7 +8,7 @@
 # 	The items are yielded in reverse order.
 # 	@parameter item [Integer]
 # 		The item will always be negative.
-# For more details see {Array}.
+# For more details see ruby:`Array`.
 def each
 end
 

test/decode/comment/text.rb

@@ -39,7 +39,7 @@
 		it "can extract top level text" do
 			expect(documentation.text).to be == [
 				"Iterates over all the items.",
-				"For more details see {Array}.",
+				"For more details see ruby:`Array`.",
 			]
 		end
 	end