Improve indentation test coverage and documentation#701
Merged
Conversation
…and try/catch/finally These forms all have indent specs but lacked dedicated tests verifying their indentation output: - defmethod with dispatch values (:defn style) - Multi-arity defn with and without docstrings/metadata - Nested letfn verifying the complex '(1 ((:defn)) nil) spec propagates correctly through multiple nesting levels - try/catch/finally verifying specs 0/2/0
Test the as-> form (spec 2) and two implicit indentation behaviors in clojure-indent-function: - with-* forms get body-style indentation even without explicit indent specs (e.g., with-custom-thing) - Unknown def* forms (defwhatever, ns/defwhatever) also get body-style indentation via the fallback regex match
Test condp (spec 2, two special args before body) and verify that namespace-qualified versions of special forms (clojure.core/let, clojure.core/when, clojure.core/defn) indent correctly via the backtracking mechanism.
These :defn-style forms had indent specs but no dedicated tests verifying body indentation. Includes fn with name, multi-arity fn, and def with metadata.
Test if, if-not, case, when, when-not, when-first, while (spec 1), and do, delay, future, comment (spec 0).
Test binding, loop, for, doseq, dotimes, when-let, if-let, when-some, if-some, doto, locking, fdef, and this-as. All use spec 1 (one special arg before body).
Test library-specific indent specs: - clojure.test: testing (1), deftest (:defn), are (2), use-fixtures (:defn), async (1) - core.logic: run (:defn), run* (:defn), fresh (:defn) - core.async: go (0), go-loop (1), thread (0), alt! (0), alt!! (0)
The backtracking indent mechanism was poorly documented — the README showed incorrect specs and didn't explain how positional indexing works, and the docstrings were minimal. README changes: - Replace the vague "more sophisticated indent specifications" section with a detailed explanation of how backtracking works, including a table of spec elements and annotated examples for letfn and defrecord - Update the built-in specs to match the actual code - Rewrite the performance section with specifics about which forms break when backtracking is disabled Docstring changes: - clojure-use-backtracking-indent: explain what it does and what breaks when disabled - clojure-max-backtracking: clarify relationship to backtracking - clojure--find-indent-spec-backtracking: document the algorithm and positional indexing with an example - clojure-indent-function: document list specs and the def*/with-* fallback behavior - put-clojure-indent: document all allowed INDENT values with examples
Test all three values (always-align, always-indent, align-arguments) with :require forms inside ns, covering both case A (arg on same line as keyword) and case B (no args on same line).
Verify that when backtracking is disabled: - Simple specs (integer, :defn) still work correctly - Complex list-based specs (letfn) lose nested context
Verify that setting max-backtracking to 0 prevents context lookup for nested forms, while the default depth of 3 allows it.
Verify that when indent specs are disabled: - Forms like let and when get uniform (function-call) indentation instead of their special body-style indentation - The def*/with-* fallback still applies regardless, since it's handled outside the spec lookup
Verify that the custom indent spec lookup hook works: - A custom function can provide specs for unknown forms - When the custom function returns nil, built-in specs still apply
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Comprehensive improvements to the indentation test suite and documentation for the backtracking indentation mechanism.
Test coverage goes from 355 to 415 specs, covering every built-in
define-clojure-indentform and all configuration knobs.New tests for built-in indent specs:
defmethod, multi-aritydefn, nestedletfn,try/catch/finallyas->,with-*fallback,def*fallbackcondp, namespace-qualified special formsfn,def,bound-fnif,if-not,case,when,when-not,when-first,while,do,delay,future,commentbinding,loop,for,doseq,dotimes,when-let,if-let,when-some,if-some,doto,locking,fdef,this-astesting,deftest,are,use-fixtures,async(clojure.test)run,run*,fresh(core.logic)go,go-loop,thread,alt!,alt!!(core.async)New tests for configuration options:
clojure-indent-keyword-style— all three values with case A/Bclojure-use-backtracking-indentnil — simple specs work, complex specs degradeclojure-max-backtracking— depth limitingclojure-enable-indent-specsnil — uniform indentation, def*/with-* fallbackclojure-get-indent-function— custom spec lookup hookDocumentation improvements for backtracking indentation in the README (spec element table, annotated letfn/defrecord examples, correct built-in specs) and in docstrings (
clojure-use-backtracking-indent,clojure-max-backtracking,clojure--find-indent-spec-backtracking,clojure-indent-function,put-clojure-indent).