branch: elpa/cider
commit da4a5bbebb6c6cbe182a55f87484ce5ab7e0d00a
Author: Bozhidar Batsov <[email protected]>
Commit: Bozhidar Batsov <[email protected]>
Define key indentation concepts and explain rule semantics
Add clear definitions for body-style indentation, special arguments,
depth, and position — terms that were used throughout the docs but
never explicitly defined. Expand the rule type descriptions with
concrete explanations of what each depth level means.
Explicitly call out cljfmt format compatibility with a link.
---
doc/modules/ROOT/pages/indent_spec.adoc | 56 +++++++++++++++++++++++++++++----
1 file changed, 50 insertions(+), 6 deletions(-)
diff --git a/doc/modules/ROOT/pages/indent_spec.adoc
b/doc/modules/ROOT/pages/indent_spec.adoc
index 0f8bea5aaf..3d7b18d604 100644
--- a/doc/modules/ROOT/pages/indent_spec.adoc
+++ b/doc/modules/ROOT/pages/indent_spec.adoc
@@ -22,21 +22,65 @@ clojure-mode 6).
=== Modern format (preferred)
The modern format uses explicit rule tuples and is shared across
`clojure-mode`,
-`clojure-ts-mode`, and `cljfmt`. Each rule is a vector of the form
-`[:block N]` or `[:inner D]` or `[:inner D I]`:
+`clojure-ts-mode`, and https://github.com/weavejester/cljfmt[cljfmt]. The
+format is identical in all three tools, so indent specs are portable across
+editors and formatters.
+
+==== Key concepts
+
+Before diving into the rules, here are the terms used throughout:
+
+**Body-style indentation**:: Arguments are indented by 2 spaces relative to the
+enclosing form. This is the standard indentation for macro bodies:
++
+[source,clojure]
+----
+(when true
+ (foo) ;; body — indented 2 spaces
+ (bar))
+----
+
+**Special arguments**:: Arguments that precede the body. When placed on their
+own line, they get additional indentation to visually distinguish them from
+the body:
++
+[source,clojure]
+----
+(defrecord TheNameOfTheRecord
+ [a pretty long argument list] ;; special arg — extra indentation
+ SomeType ;; body — standard 2-space indentation
+ (method [this] ...))
+----
+
+**Depth**:: The nesting level within the form, counting from 0. Depth 0 is the
+form's direct arguments, depth 1 is the arguments _inside_ those arguments,
+depth 2 is one level deeper, and so on.
+
+**Position**:: The 0-indexed argument position within the enclosing form
+(excluding the form name itself). For example, in `(let [x 1] body)`, the
+binding vector `[x 1]` is at position 0 and `body` is at position 1.
+
+==== Rule types
+
+Each rule is a vector of the form `[:block N]`, `[:inner D]`, or `[:inner D
I]`:
[cols="1,3"]
|===
| Rule | Meaning
| `[:block N]`
-| The first N arguments are "special" (indented further); remaining arguments
are body.
+| The first N arguments are "special" (indented further when on their own
line);
+remaining arguments get body-style indentation (2 spaces).
| `[:inner D]`
-| At nesting depth D inside the form, use body-style indentation.
+| At nesting depth D inside the form, all sub-forms get body-style indentation.
+`[:inner 0]` means direct arguments are body-indented (like `defn`).
+`[:inner 1]` means forms _inside_ the arguments are body-indented (like method
+bodies in `defprotocol`).
| `[:inner D I]`
-| Like `:inner`, but only applies at position I within the enclosing form.
+| Like `[:inner D]`, but restricted to position I within the enclosing form.
+Used when only some arguments at a given depth need body-style indentation.
|===
Rules are combined in a vector. For example:
@@ -44,7 +88,7 @@ Rules are combined in a vector. For example:
* `1` or `[[:block 1]]` — one special arg, then body (e.g., `when`, `let`)
* `:defn` or `[[:inner 0]]` — all args are body (e.g., `defn`, `fn`)
* `[[:block 2] [:inner 1]]` — two special args, nested sub-forms get body
indent (e.g., `defrecord`, `deftype`)
-* `[[:block 1] [:inner 2 0]]` — one special arg, depth-2 nesting at position 0
(e.g., `letfn`)
+* `[[:block 1] [:inner 2 0]]` — one special arg, depth-2 nesting at position 0
only (e.g., `letfn`)
Simple specs (an integer or `:defn`) are shorthand for the corresponding
single-rule vector.
