Documentation: public needs global scope (JuliaLang#57916)

Author: PatrickHaecker

doc/src/devdocs/ast.md

@@ -119,10 +119,18 @@ parses as `(macrocall (|.| Core '@doc) (line) "some docs" (= (call f x) (block x
 | `import Base: x`    | `(import (: (. Base) (. x)))`                |
 | `import Base: x, y` | `(import (: (. Base) (. x) (. y)))`          |
 | `export a, b`       | `(export a b)`                               |
+| `public a, b`       | `(public a b)`                               |
 
 `using` has the same representation as `import`, but with expression head `:using`
 instead of `:import`.
 
+To programmatically create a `public` statement, you can use `Expr(:public, :a, :b)` or,
+closer to regular code, `Meta.parse("public a, b")`. This approach is necessary due to
+[current limitations on `public`](@ref Export-lists). The `public` keyword is only
+recognized at the syntactic top level within a file (`parse_stmts`) or module. This
+restriction was implemented to prevent breaking existing code that used `public` as an
+identifier when it was introduced in Julia 1.11.
+
 ### Numbers
 
 Julia supports more number types than many scheme implementations, so not all numbers are represented

doc/src/manual/modules.md

@@ -114,6 +114,12 @@ and above. To maintain compatibility with Julia 1.10 and below, use the `@compat
 VERSION >= v"1.11.0-DEV.469" && eval(Meta.parse("public a, b, c"))
 ```
 
+`export` is a keyword wherever it occurs whereas the `public` keyword is currently limited to the
+syntactic top level within a file or module. This limitation exists for compatibility reasons,
+as `public` was introduced as a new keyword in Julia 1.11 while `export` has existed since Julia
+1.0. However, this restriction on `public` may be lifted in future releases, so do not use `public`
+as an identifier.
+
 ### Standalone `using` and `import`
 
 For interactive use, the most common way of loading a module is `using ModuleName`. This [loads](@ref