editing updates

Author: puredanger

content/reference/java_interop.adoc

@@ -78,7 +78,7 @@ The unqualified "." forms expand into calls to the dot operator (described below
 [[methodvalues]]
 === Method values
 
-Since Clojure 1.12, programmers can use Java qualified methods as ordinary functions in value contexts - the compiler will automatically generate the wrapping function. When used as values, qualified methods supply only the class and method name, and thus cannot resolve overloaded methods. Therefore, the compiler will generate a reflective call when a qualified method does not resolve due to overloading. Developers can supply <<param-tags#,:param-tags metadata>> on qualified methods to specify the signature of a single desired method, 'resolving' it.
+Since Clojure 1.12, programmers can use Java qualified methods as ordinary functions in value contexts - the compiler will automatically generate the wrapping function. When used as values, qualified methods supply only the class and method name, and thus cannot resolve overloaded methods. Therefore, the compiler will generate a reflective call when a qualified method does not resolve due to overloading. Developers can supply <<java_interop#paramtags,:param-tags metadata>> on qualified methods to specify the signature of a single desired method, 'resolving' it. `:param-tags` are ignored on unqualified methods like `.instanceMember`.
 
 == The Dot special form
 
@@ -164,7 +164,7 @@ Since Clojure 1.12, a qualified form may also be used (it is not rewritten at ma
 
 `(Classname/new args*)`
 
-Like methods, qualified constructors `Classname/new` can be used in <<methodvalues#,value contexts>>.
+Like methods, qualified constructors `Classname/new` can be used in <<methodvalues#,value contexts>> and take <<java_interop#paramtags,:param-tags>> metadata.
 
 ''''
 
@@ -343,7 +343,7 @@ For example, byte arrays (byte-array []) have a type of "[B".
 * chars - A character array
 * objects - An object array
 
-[[param-tags]]
+[[paramtags]]
 == param-tags
 
 Since Clojure 1.12, developers can supply `:param-tags` metadata on qualified methods to specify the signature of a single desired method, 'resolving' it. The `:param-tags` metadata is a vector of zero or more tags: `[... tag ...]`. A tag is any existing valid `:tag` metadata value as described above. Each tag corresponds to a parameter in the desired signature (arity should match the number of tags). Parameters with non-overloaded types can use the placeholder `_` in lieu of the tag. When you supply :param-tags metadata on a qualified method, the metadata must allow the compiler to resolve it to a single method at compile time.
@@ -437,7 +437,7 @@ At times it is necessary to have a value of a particular primitive type. These c
 
 === Functional interfaces
 
-Java programs define "functions" with Java functional interfaces (marked with the  https://docs.oracle.com/javase/8/docs/api/java/lang/FunctionalInterface.html[@FunctionalInterface] annotation), which have a single method.
+Java defines "functions" with Java functional interfaces (marked with the  https://docs.oracle.com/javase/8/docs/api/java/lang/FunctionalInterface.html[@FunctionalInterface] annotation), which have a single method.
 
 Since, Clojure 1.12, developers can invoke Java methods taking functional interfaces by passing functions with matching arity. The Clojure compiler implicitly converts Clojure functions to the required functional interface by constructing a lambda adapter. You can explicitly coerce a Clojure function to a functional interface by <<special_forms#let,hinting the binding name>> in a `let` binding, e.g. to avoid repeated adapter construction in a loop.
 

content/reference/metadata.adoc

@@ -77,19 +77,19 @@ Returns an object of the same type and value as obj, with `(apply f (meta obj) a
 
 Modify or reset the metadata respectively for a namespace/var/ref/agent/atom.
 
-== Metadata Reader Macros
+== Metadata Reader Syntax
 
-In addition to with-meta, there are a number of reader macros (<<reader#macrochars,The Reader: Macro Characters>>) for applying metadata to the expression following it at read-time:
+In addition to with-meta, there is reader support (<<reader#metadata,Metadata Reader>>) for applying metadata to the expression following it at read-time:
 
-* `^{:doc "How it works!"}` - adds the metadata map to the metadata of the next value read
-* `^:dynamic` -> `^{:dynamic true}`
-* `^String` -> `^{:tag java.lang.String}`
-* `^"java.lang.String"` -> `^{:tag java.lang.String}`
-* `^[String long _]` -> `^{:param-tags [String long _]}`
+* Map: `^{:key value ...}`
+* Keyword: `^:key -> `^{:key true}`
+* Symbol: `^AClass` or `^package.AClass` -> `{:tag package.AClass}` (also see special <<java_interop#TypeAliases,type aliases>>)
+* String: `^"package.AClass"` -> `{:tag package.AClass}`
+* Vector: `^[AClass prim _ ...]` -> `{:param-tags [package.AClass prim _ ...]}`
 
 The `:tag` key is used to hint an objects type to the Clojure compiler. See <<java_interop#typehints,Java Interop: Type Hints>> for more information and a complete list of special type hints.
 
-Since Clojure 1.12, the `:param-tags` key is used on `Classname/member` and `Classname/new` symbols to specify the arity and parameter types of the desired method. The `:param-tags` vector takes any valid `:tag` value or `_` as a placeholder for non-overloaded parameters.
+Since Clojure 1.12, the `:param-tags` key is used on qualified static, instance, and constructor method symbols to specify the arity and parameter types of the desired method overload. The `:param-tags` vector takes any valid `:tag` value or `_` as a placeholder for non-overloaded parameters.
 
 It is possible to add multiple pieces of metadata by chaining the metadata reader macros together.
 For example: `^:dynamic ^ints obj` would apply both the :dynamic flag and ints type-hint to obj. Metadata chains from right to left (left takes precedence).

content/reference/reader.adoc

@@ -134,14 +134,17 @@ Single-line comment, causes the reader to ignore everything from the semicolon t
 
 `@form => (deref form)`
 
+[[metadata]]
 === Metadata (^)
 
 Metadata is a map associated with some kinds of objects: Symbols, Lists, Vector, Sets, Maps, tagged literals returning an IMeta, and record, type, and constructor calls. The metadata reader macro first reads the metadata and attaches it to the next form read (see https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/with-meta[with-meta] to attach meta to an object): +
 `^{:a 1 :b 2} [1 2 3]` yields the vector `[1 2 3]` with a metadata map of `{:a 1 :b 2}`. +
 
-A shorthand version allows the metadata to be a simple symbol or string, in which case it is treated as a single entry map with a key of :tag and a value of the (resolved) symbol or string, e.g.: +
+A shorthand version allows the metadata to be a simple symbol or string, in which case it is treated as a single entry map with a key of `:tag` and a value of the (resolved) symbol or string, e.g.: +
 `^String x` is the same as `^{:tag java.lang.String} x` +
 
+A shorthand version for type signatures allows the metadata to be a vector, in which case it is treated as a single entry map with a key of `:param-tags` and a value of the (resolved) type hints, a vector of `:tag` values or `_`, e.g.: `^[String long _]` is the same as `^{:param-tags [java.lang.String long _]}`.
+
 Such tags can be used to convey type information to the compiler. +
 
 Another shorthand version allows the metadata to be a keyword, in which case it is treated as a single entry map with a key of the keyword and a value of true, e.g.: +

content/reference/repl_and_main.adoc

@@ -172,7 +172,7 @@ Because the `user.clj` file is loaded by the Clojure runtime on initialization,
 
 The <<xref/../../../guides/install_clojure#,Clojure CLI>> can be used to <<deps_edn#,declare dependencies>> loaded at REPL startup time. Since Clojure 1.12, you can also dynamically load libraries at the REPL for interactive use. These functions are available in the `clojure.repl.deps` namespace:
 
-* https://clojure.github.io/clojure/clojure.repl-api.html#clojure.repl.deps/add-lib[`add-lib`] takes a lib that is not available on the classpath, and makes it available by downloading (if necessary) and adding to the classloader. Libs already on the classpath are not updated. If the coordinate is not provided, the newest Maven or git (if the library has an inferred git repo name) version or tag are used.
+* https://clojure.github.io/clojure/clojure.repl-api.html#clojure.repl.deps/add-lib[`add-lib`] takes a lib that is not available on the classpath, and makes it available by downloading (if necessary) and adding to the classloader. Libs already on the classpath are not updated. If the coordinate is not provided, the newest Maven version or git tag (if the library has an inferred git repo name) are used.
 * https://clojure.github.io/clojure/clojure.repl-api.html#clojure.repl.deps/add-libs[`add-libs`] is like `add-lib`, but resolves a set of new libraries and versions together.
 * https://clojure.github.io/clojure/clojure.repl-api.html#clojure.repl.deps/sync-deps[`sync-deps`] calls `add-libs` with any libs present in <<deps_edn#,deps.edn>>, but not yet present on the classpath.
 

content/reference/special_forms.adoc

@@ -101,7 +101,7 @@ Evaluates the expressions __expr__s in a lexical context in which the symbols in
 -> 1
 ----
 
-If the _binding_ symbol metadata tag is a Java interface annotated as a https://docs.oracle.com/javase/8/docs/api/java/lang/FunctionalInterface.html[FunctionalInterface], the __init-expr__ will be coerced (if necessary) from the Clojure `IFn` interface to the specified interface:
+If the _binding_ symbol metadata tag is a Java interface annotated as a https://docs.oracle.com/javase/8/docs/api/java/lang/FunctionalInterface.html[FunctionalInterface], the __init-expr__ will be coerced (if necessary) to the specified interface:
 
 [source,clojure]
 ----