From 52a3125f39ac017485076714f5e2cdafb8ca9fc4 Mon Sep 17 00:00:00 2001
From: Vinicius Stock <vinicius.stock@shopify.com>
Date: Wed, 24 Dec 2025 11:55:43 -0300
Subject: [PATCH] Mention the comment type annotations in docs

---
 AGENTS.md       | 31 +++++++++++++++++++++++++++++++
 CONTRIBUTING.md |  9 +++++++++
 2 files changed, 40 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index c984184190..ddfdc9f664 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -82,6 +82,37 @@ npx stylelint "lib/rdoc/generator/template/aliki/css/rdoc.css"
 - Style and formatting checks
 - Many issues auto-fixable with `--fix`
 
+### Type annotations
+
+Annotate method types using [Sorbet flavored RBS](https://sorbet.org/docs/rbs-support) in inline comments.
+For more information about RBS syntax, see the [documentation](https://github.com/ruby/rbs/blob/master/docs/syntax.md).
+
+A few examples:
+
+```ruby
+# Method that receives an integer and doesn't return anything
+#: (Integer) -> void
+def foo(something); end
+
+# Method that receives a string and returns an integer
+#: (String) -> Integer
+def bar(something)
+   123
+end
+
+# Method that doesn't accept arguments and returns a hash of symbol to string
+#: () -> Hash[Symbol, String]
+def bar
+   { key: "value" }
+end
+
+# Method that accepts a block, which yields a single integer argument and returns whatever the block returns
+#: [T] () { (Integer) -> T } -> T
+def bar
+   yield(5)
+end
+```
+
 ### Documentation Generation
 
 ```bash
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6cff518bde..9911267cc5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -86,6 +86,15 @@ npm run lint:css
 npm run lint:css -- --fix
 ```
 
+## Type annotations
+
+RDoc is currently not a typed codebase. Despite not running a type checker, contributors have been
+adding some comment annotations to make the codebase easier to navigate and understand.
+
+These annotations use [Sorbet flavored RBS](https://sorbet.org/docs/rbs-support) annotations,
+so that we can tag definitions as abstract and override. For more information on RBS syntax,
+see the [documentation](https://github.com/ruby/rbs/blob/master/docs/syntax.md).
+
 ## Parser Generation
 
 RDoc uses generated parsers for Markdown and RD formats.