From 219ee356d2f7952cd81d800e14dc72d8c57503cf Mon Sep 17 00:00:00 2001
From: Earlopain <14981592+Earlopain@users.noreply.github.com>
Date: Wed, 14 Jan 2026 13:23:47 +0100
Subject: [PATCH] Update ripper translation docs

* Prefer `Prism::Translation::Ripper` over the ripper shim
* Don't list what is available (`Ripper::SexpBuilder` is nodoc)
---
 docs/ripper_translation.md | 25 ++++++++-----------------
 1 file changed, 8 insertions(+), 17 deletions(-)

diff --git a/docs/ripper_translation.md b/docs/ripper_translation.md
index 196eeb811c..92bbe74569 100644
--- a/docs/ripper_translation.md
+++ b/docs/ripper_translation.md
@@ -1,22 +1,6 @@
 # Ripper translation
 
-Prism provides the ability to mirror the `Ripper` standard library. You can do this by:
-
-```ruby
-require "prism/translation/ripper/shim"
-```
-
-This provides the APIs like:
-
-```ruby
-Ripper.lex
-Ripper.parse
-Ripper.sexp_raw
-Ripper.sexp
-
-Ripper::SexpBuilder
-Ripper::SexpBuilderPP
-```
+Prism provides the ability to mirror the `Ripper` standard library. It is available under `Prism::Translation::Ripper`. You can use the entire public API, and also some undocumented features that are commonly used.
 
 Briefly, `Ripper` is a streaming parser that allows you to construct your own syntax tree. As an example:
 
@@ -49,6 +33,13 @@ ArithmeticRipper.new("1 + 2 - 3").parse # => [0]
 
 The exact names of the `on_*` methods are listed in the `Ripper` source.
 
+You can can also automatically use the ripper translation in places that don't explicitly use the translation layer by doing the following:
+
+```ruby
+# Will redirect access of the `Ripper` constant to `Prism::Translation::Ripper`.
+require "prism/translation/ripper/shim"
+```
+
 ## Background
 
 It is helpful to understand the differences between the `Ripper` library and the `Prism` library. Both libraries perform parsing and provide you with APIs to manipulate and understand the resulting syntax tree. However, there are a few key differences.