From 056a287c962f3d66b1d98a080182fd2f7ae76ff4 Mon Sep 17 00:00:00 2001
From: Kristoffer Carlsson <kcarlsson89@gmail.com>
Date: Tue, 24 Sep 2024 10:02:47 +0200
Subject: [PATCH] privatize annotated string API, take two (#55845)

https://github.com/JuliaLang/julia/pull/55453 is stuck on StyledStrings
and Base documentation being entangled and there isn't a good way to
have the documentation of Base types / methods live in an stdlib. This
is a stop gap solution to finally be able to move forwards with 1.11.

(cherry picked from commit db6d277f6226daa5739940a4642277cfe0a884ea)
---
 base/exports.jl           |  7 -------
 base/strings/annotated.jl | 14 --------------
 doc/src/base/strings.md   | 19 ++++++++++++++-----
 doc/src/manual/strings.md |  4 ++++
 4 files changed, 18 insertions(+), 26 deletions(-)

diff --git a/base/exports.jl b/base/exports.jl
index 3bacc5cd10aff..a8254d434a1f5 100644
--- a/base/exports.jl
+++ b/base/exports.jl
@@ -1096,15 +1096,8 @@ public
     Lockable,
     OneTo,
     LogRange,
-    AnnotatedString,
-    AnnotatedChar,
     UUID,
 
-# Annotated strings
-    annotatedstring,
-    annotate!,
-    annotations,
-
 # Semaphores
     Semaphore,
     acquire,
diff --git a/base/strings/annotated.jl b/base/strings/annotated.jl
index ef1ea28f42738..b54cbf855ba9b 100644
--- a/base/strings/annotated.jl
+++ b/base/strings/annotated.jl
@@ -39,13 +39,6 @@ the combined range.
 See also [`AnnotatedChar`](@ref), [`annotatedstring`](@ref),
 [`annotations`](@ref), and [`annotate!`](@ref).
 
-!!! warning
-    While the constructors are part of the Base public API, the fields
-    of `AnnotatedString` are not. This is to allow for potential future
-    changes in the implementation of this type. Instead use the
-    [`annotations`](@ref), and [`annotate!`](@ref) getter/setter
-    functions.
-
 # Constructors
 
 ```julia
@@ -81,13 +74,6 @@ More specifically, this is a simple wrapper around any other
 See also: [`AnnotatedString`](@ref), [`annotatedstring`](@ref), `annotations`,
 and `annotate!`.
 
-!!! warning
-    While the constructors are part of the Base public API, the fields
-    of `AnnotatedChar` are not. This it to allow for potential future
-    changes in the implementation of this type. Instead use the
-    [`annotations`](@ref), and [`annotate!`](@ref) getter/setter
-    functions.
-
 # Constructors
 
 ```julia
diff --git a/doc/src/base/strings.md b/doc/src/base/strings.md
index ef470be6b55cc..fb09c6aee78a2 100644
--- a/doc/src/base/strings.md
+++ b/doc/src/base/strings.md
@@ -17,11 +17,6 @@ Core.String(::AbstractString)
 Base.SubString
 Base.LazyString
 Base.@lazy_str
-Base.AnnotatedString
-Base.AnnotatedChar
-Base.annotatedstring
-Base.annotations
-Base.annotate!
 Base.transcode
 Base.unsafe_string
 Base.ncodeunits(::AbstractString)
@@ -98,3 +93,17 @@ Base.escape_string
 Base.escape_raw_string
 Base.unescape_string
 ```
+
+## `AnnotatedString`s
+
+!!! note
+    The API for AnnotatedStrings is considered experimental and is subject to change between
+    Julia versions.
+
+```@docs
+Base.AnnotatedString
+Base.AnnotatedChar
+Base.annotatedstring
+Base.annotations
+Base.annotate!
+```
diff --git a/doc/src/manual/strings.md b/doc/src/manual/strings.md
index f4acffb2ae91b..28fa4a7ca6d76 100644
--- a/doc/src/manual/strings.md
+++ b/doc/src/manual/strings.md
@@ -1207,6 +1207,10 @@ last backslash escapes a quote, since these backslashes appear before a quote.
 
 ## [Annotated Strings](@id man-annotated-strings)
 
+!!! note
+    The API for AnnotatedStrings is considered experimental and is subject to change between
+    Julia versions.
+
 It is sometimes useful to be able to hold metadata relating to regions of a
 string. A [`AnnotatedString`](@ref Base.AnnotatedString) wraps another string and
 allows for regions of it to be annotated with labelled values (`:label => value`).