add section on var metadata tags in vars page, #534

content/reference/vars.adoc

@@ -93,6 +93,27 @@ The <<special_forms#var,var>> special form or the `pass:[#']` reader macro _(see
 
 It is possible to create vars that are not interned by using https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/with-local-vars[with-local-vars]. These vars will not be found during free symbol resolution, and their values have to be accessed manually. But they can serve as useful thread-local mutable cells.
 
+[[metadata]]
+== Var metadata
+
+The forms that create vars `def`, `defn`, `defmacro`, etc use a standard set of var <<metadata#,metadata>> to describe vars. Some of these forms provide explicit places in the syntax to provide values stored in the metadata, but generally you can also supply that metadata as a map on the var symbol.
+
+Common var metadata keys (all optional at var definition):
+
+* `:doc` - a string documenting the var, usually set by the docstring parameter
+* `:added` - a string documenting the version when this var was added
+* `:private` a boolean flag, often set by `defn-`, used by the author to state the intent that this var is an implementation detail. Private vars are globally accessible but will not be referred or listed in `ns-`... functions which filter to non-private vars.
+* `:arglists` - a coll of arglists, will be generated automatically if not supplied, most often used to document macro syntax
+* `:macro` - a boolean flag added by `defmacro` automatically (not typically used directly)
+* `:tag` - a type identifier (usually a class) for the type of the value in the var or the return type of a function held in the var. Note that var metadata is evaluated, so type hints like `^long` on the var will evaluate to the `long` function, not a `long` primitive type hint. Generally, it is preferred to use a type hint on the arglist for defn vars instead.
+* `:test` - the `clojure.test` framework attaches unit tests to vars using this key (not typically used directly)
+* `:dynamic` - indicates a var may be dynamically rebound in a thread context (see above). Dynamic vars will not be direct linked when compiling with direct linking.
+* `:redef` - indicates that a var should not be direct linked when compiling with direct linking (thus allowing it to be redefined)
+* `:static` - no longer used (originally vars were dynamic by default, now they are static by default)
+* `:const` - indicates that a var is a compile-time constant and the compiler can inline the value into code that uses it. Note: this is rarely needed and only works with constants at compile time (read, but not evaluated), such as numbers, strings, etc (NOT classes, functions, ref types, etc). Redefining or dynamically binding a const var will not affect code that consumes the var that has already been compiled and loaded in the runtime.
+
+Also see <<compilation#_compiler_options,Compiler Options>> for more information about direct linking and metadata elision during compilation.
+
 [[related]]
 == Related functions
 
@@ -101,4 +122,4 @@ Variants of `def`: https://clojure.github.io/clojure/clojure.core-api.html#cloju
 Working with interned Vars: https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/declare[declare] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/intern[intern] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/binding[binding] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/find-var[find-var] <<special_forms#var,var>>
 Working with Var objects: https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/with-local-vars[with-local-vars] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/var-get[var-get] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/var-set[var-set] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/alter-var-root[alter-var-root] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/var?[var?] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/with-redefs[with-redefs] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/with-redefs-fn[with-redefs-fn]
 Var validators: https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/set-validator![set-validator!] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/get-validator[get-validator]
-Common Var metadata: https://clojure.github.io/clojure/clojure.repl-api.html#clojure.repl/doc[doc] https://clojure.github.io/clojure/clojure.repl-api.html#clojure.repl/find-doc[find-doc] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/test[test]
+Using Var metadata: https://clojure.github.io/clojure/clojure.repl-api.html#clojure.repl/doc[doc] https://clojure.github.io/clojure/clojure.repl-api.html#clojure.repl/find-doc[find-doc] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/test[test]