doc edits, wip

Author: puredanger

content/reference/java_interop.adoc

@@ -23,7 +23,7 @@ toc::[]
 
 Symbols representing class names are resolved to the Class instance. Inner or nested classes are separated from their outer class with a `$`. Fully-qualified class names are always valid. If a class is `import`ed in the namespace, it may be used without qualification. All classes in java.lang are automatically imported to every namespace.
 
-Since 1.12, class qualified symbols may have a name part of a single digit between 1 and 9, inclusive to refer to an array of the class. The digit indicates the array dimension. Array classes may also use a primitive component, e.g. `long/1`.
+A symbol whose ns-part names a class or a primitive, and whose name part is a single digit between 1 and 9, designates an array class of that component type and dimension. Added in 1.12.
 
 [source,clojure-repl]
 ----
@@ -62,9 +62,9 @@ Math/PI
 
 ----
 
-The preferred idiomatic forms for accessing field or method members are given above. The instanceMember form works for both fields and methods. The instanceField form is preferred for fields and required if both a field and a 0-argument method of the same name exist.
+The preferred idiomatic forms for accessing field or method members are given above. The instanceMember form works for both fields and methods. The instanceField form is required if both a field and a 0-argument method of the same name exist.
 
-Since Clojure 1.12, `Classname/.instanceMethod` refers to a qualified instance method. When an instance method is specified, the instance should be provided after the member and before the args. When a qualified instance method is present then the qualifying class takes precedence over any additional type information on the instance for the purpose of resolving the instance method.
+Since Clojure 1.12, `Classname/.instanceMethod` refers to an instance method. When an instance method is specified, the instance should be provided after the member and before the args. When a qualified instance method is present then the qualifying class takes precedence over any additional type information on the instance for the purpose of resolving the instance method.
 
 The unqualified "." forms expand into calls to the dot operator (described below) at macroexpansion time. The expansions are as follows:
 
@@ -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 <<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`.
+Since Clojure 1.12, programmers can use 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
 
@@ -435,11 +435,12 @@ both takes and returns values of primitive type `long` (invocations with a boxed
 
 At times it is necessary to have a value of a particular primitive type. These coercion functions yield a value of the indicated type as long as such a coercion is possible: https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/bigdec[bigdec] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/bigint[bigint] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/boolean[boolean] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/byte[byte] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/char[char] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/double[double] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/float[float] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/int[int] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/long[long] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/num[num] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/short[short]
 
+[[functional_interfaces]]
 == Functional Interface Conversion
 
-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 programs emulate functions with https://docs.oracle.com/javase/8/docs/api/java/lang/FunctionalInterface.html[Functional Interfaces], which have a single method.
 
-When invoking Java methods or constructors, 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 hinting the binding name in a let binding, e.g. to avoid repeated adapter construction in a loop, e.g. (let [^java.util.function.Predicate p even?] ...).
+Clojure developers can invoke Java methods taking Functional Interfaces by passing functions with matching arity. The Clojure compiler implicitly converts functions to the required Functional Interface by constructing a lambda adapter. You can explicitly coerce a function to a Functional Interface by hinting the binding name in a `let` binding, e.g. to avoid repeated adapter construction in a loop, e.g. `(let [^java.util.function.Predicate p even?] ...)`.
 
 Since Clojure 1.12, all `IDeref` impls (`delay`, `future`, `atom`, etc) implement the https://docs.oracle.com/javase/8/docs/api/java/util/function/Supplier.html[Supplier] interface directly.
 

content/reference/metadata.adoc

@@ -86,8 +86,8 @@ For a metadata value of type:
 * Map: `^{:key value ...}` yields itself
 * Keyword: `^:key` yields `^{:key true}`
 * Symbol: `^AClass` or `^package.AClass` yields `{:tag package.AClass}` (also see special <<java_interop#TypeAliases,type aliases>>)
-* String: `^"package.AClass"` yields `{:tag package.AClass}`
 * Vector: `^[AClass prim _ ...]` yields `{:param-tags [package.AClass prim _ ...]}`
+* *deprecated* String: `^"[Lpackage.AClass;"` yields `{:tag "[Lpackage.AClass;"}` - since 1.12, use array class symbols instead, e.g. `^package.AClass/1`
 
 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.