From 612ce0f202cfa1bc347408afc56b7a773a2cdbb7 Mon Sep 17 00:00:00 2001
From: KristofferC <kristoffer.carlsson@juliacomputing.com>
Date: Mon, 23 Sep 2024 14:35:59 +0200
Subject: [PATCH] privatize annotated string API, take two

---
 base/public.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/public.jl b/base/public.jl
index 803766a0cec1b..2e8e777d2f91d 100644
--- a/base/public.jl
+++ b/base/public.jl
@@ -21,15 +21,8 @@ public
     ImmutableDict,
     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 be4c6887d4a6d..9a0b4b2825436 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 b7d16ffc7d487..a9637a1a7be3a 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)
@@ -101,3 +96,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 5ba27b3921cec..c04e5e6d6760e 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`).