branch: elpa/cider
commit d5de076bbc61b75727296b78825ba94557dac00d
Author: Bozhidar Batsov <[email protected]>
Commit: Bozhidar Batsov <[email protected]>
Update Special Arguments and Internal Indentation sections
Rewrite the Special Arguments section to reference [:block N] rule
and add depth annotations to examples. Rewrite the Internal
Indentation section to explain [:inner 1] in terms of depth rather
than legacy positional semantics.
Add a new Namespace-Qualified Symbols section documenting
clojure-mode's support for per-namespace indent overrides and the
automatic fallback to unqualified specs.
---
doc/modules/ROOT/pages/indent_spec.adoc | 48 +++++++++++++++++++++++----------
1 file changed, 34 insertions(+), 14 deletions(-)
diff --git a/doc/modules/ROOT/pages/indent_spec.adoc
b/doc/modules/ROOT/pages/indent_spec.adoc
index c75ccaf4a7..b44f90c522 100644
--- a/doc/modules/ROOT/pages/indent_spec.adoc
+++ b/doc/modules/ROOT/pages/indent_spec.adoc
@@ -233,17 +233,18 @@ For reference, the same specs in the legacy positional
format:
Many macros have a number of "special" arguments, followed by an arbitrary
number of "non-special" arguments (sometimes called the body). The
"non-special"
-arguments have a small indentation (usually 2 spaces). The special arguments
+arguments have body-style indentation (2 spaces). The special arguments
are usually on the same line as the macro name, but, when necessary, they are
placed on a separate line with additional indentation.
-For instance, `defrecord` has two special arguments, and here's how it might
be indented:
+This is controlled by the `[:block N]` rule. For instance, `defrecord` has
+`[:block 2]` (two special arguments), and here's how it might be indented:
[source,clojure]
----
(defrecord TheNameOfTheRecord
- [a pretty long argument list]
- SomeType
+ [a pretty long argument list] ;; special arg — extra indent
+ SomeType ;; body — 2 spaces
(assoc [_ x]
(.assoc pretty x 10)))
----
@@ -261,11 +262,11 @@ Here's another way one could do it:
_The point of the indent spec is *not* to specify how many spaces to use._
-The point is just to say "a defrecord has *2* special arguments", and then let
-the editor and the user come to an agreement on how many spaces they like to
use
-for special and non-special arguments.
+The point is just to say "a defrecord has *2* special arguments" (via
+`[:block 2]`), and then let the editor and the user come to an agreement on how
+many spaces they like to use for special and non-special arguments.
-== Internal indentation
+== Internal Indentation (Depth)
The issue goes a bit deeper. Note the last argument in that `defrecord`. A
regular function form would be internally indented as:
@@ -275,18 +276,37 @@ regular function form would be internally indented as:
(.assoc pretty x 10))
----
-But this is not a regular function call, it's a definition. So we want to
-specify that this form internally has 1 special argument (the arglist vector),
-so that it will be indented like this:
+But this is not a regular function call, it's a method definition. So we want
+the method body to get body-style indentation:
----
(assoc [_ x]
(.assoc pretty x 10))
----
-The indent spec does this as well. It lets you specify that, for each argument
-beyond the 2nd, if it is a form, it should be internally indented as having 1
-special argument.
+This is what the `[:inner 1]` rule does — it says "at depth 1 (inside the
+arguments of this form), use body-style indentation." Combined with
+`[:block 2]`, the full spec `[[:block 2] [:inner 1]]` gives defrecord both
+special argument handling and correct method body indentation.
+
+== Namespace-Qualified Symbols
+
+In `clojure-mode`, you can specify different indentation for the same symbol
+depending on its namespace. This is useful when a library redefines a form
+with different semantics:
+
+[source,lisp]
+----
+;; Default indentation for `do`
+(put-clojure-indent 'do '((:block 0)))
+
+;; Custom indentation for `my-ns/do`
+(put-clojure-indent 'my-ns/do '((:block 1)))
+----
+
+When a namespace-qualified symbol has no explicit spec, `clojure-mode`
+automatically falls back to the unqualified symbol's spec. For example,
+`clojure.core/let` uses the same spec as `let`.
== Indentation inference
