improve docs & code comments

Author: monosans

README.md

@@ -23,9 +23,9 @@
 
 ## 🤔 For What?
 
-Every language in your stack has a formatter and a linter. HTML templates are the exception. Generic HTML tools can't parse `{% %}` and `{{ }}`, and template engines don't care what the markup around them looks like. Templates end up in a tooling blind spot: drifting indentation, mismatched tags and inconsistent spacing that survive every code review.
+Every language in your stack has a formatter and a linter. HTML templates are the exception. Generic HTML tools can't parse `{% %}` and `{{ }}`, and template engines don't care what the markup around them looks like. So indentation drifts, tags go unclosed and spacing goes wherever, and none of it gets caught in review.
 
-djLint covers that blind spot. It understands HTML _and_ the template syntax inside it, with profiles for Django, Jinja, Twig, Nunjucks, Handlebars, Liquid, Go templates and more.
+djLint reads HTML _and_ the template syntax inside it, with profiles for Django, Jinja, Twig, Nunjucks, Handlebars, Liquid, Go templates and more.
 
 Take a template only its author could love:
 
@@ -78,9 +78,9 @@ One `djlint --reformat --single-attribute-per-line` later:
 
 One command rebuilt the indentation, fixed the tag case, split the long tag into one attribute per line, normalized the template tags and collapsed stray blank lines.
 
-And the linter catches what formatting can't fix: orphan tags, missing `alt` attributes, hard-coded URLs and dozens of other checks.
+The linter catches what formatting can't fix: orphan tags, missing `alt` attributes, hard-coded URLs and dozens of other checks.
 
-**[Try it on your own templates in the online playground →](https://djlint.com/demo/)**
+You can [try it on your own templates in the online playground](https://djlint.com/demo/).
 
 ## ✨ How?
 
@@ -189,7 +189,7 @@ uv sync
 uv run pytest
 ```
 
-## 🏃 Other Tools Of Note
+## 🏃 Other tools of note
 
 - [djade](https://github.com/adamchainz/djade) A fast Django template formatter that formats template syntax whilst leaving HTML as-is, and applies fixes for older Django versions.
 - [djangofmt](https://github.com/UnknownPlatypus/djangofmt) A fast, HTML-aware Django/Jinja template formatter written in Rust that formats HTML and template syntax together.

docs/src/docs/getting-started.md

@@ -98,22 +98,13 @@ echo "<div></div>" | djlint - --stdin-filename templates/index.html
 | `1`  | djLint found linting errors, or files that need reformatting. `--warn` reports these as warnings and exits `0` instead.          |
 | `2`  | djLint did not check what you asked it to: the paths matched no files, the command line or config was invalid, or djLint failed. |
 
-Only code `1` means "djLint looked at your templates and did not like what it
-found". Code `2` always means the run itself did not deliver, so a pipeline can
-treat the two differently instead of guessing.
-
-That covers the "djLint checked nothing" case - a wrong path, an `--extension`
-that no longer matches, or templates that have moved - a run that would
-otherwise pass silently while checking none of your templates.
-
-Files that djLint _did_ find and then skipped on purpose - through `exclude`,
-`extend_exclude`, `use_gitignore` or `require_pragma` - are not an error. That
-run exits `0`, because the configuration did exactly what it was told to. This
-is what lets `exclude` work under pre-commit, which passes the names of your
-staged files whether or not you want djLint to look at them.
-
-If a path that legitimately has no templates is normal for your pipeline, turn
-code `2` off with `allow_empty_input`:
+Only code `1` means djLint looked at your templates and did not like what it found. Code `2` always means the run itself did not deliver, so a pipeline can treat the two differently instead of guessing.
+
+Code `2` is what catches a run that checked nothing at all: a wrong path, an `--extension` that no longer matches, or templates that have moved. Without it such a run passes silently, having looked at none of your templates.
+
+Files that djLint _did_ find and then skipped on purpose, through `exclude`, `extend_exclude`, `use_gitignore` or `require_pragma`, are not an error. That run exits `0`, because the configuration did exactly what it was told to. It is also what lets `exclude` work under pre-commit, which passes the names of your staged files whether or not you want djLint to look at them.
+
+If a path that legitimately has no templates is normal for your pipeline, turn code `2` off with `allow_empty_input`:
 
 ```bash
 djlint /path/to/templates --lint --allow-empty-input

docs/src/docs/linter.md

@@ -879,7 +879,7 @@ Do:
 
 `Avoid use of <br> tags.`
 
-`<br>` encodes presentation in markup: using it for spacing or to fake paragraphs breaks text reflow at narrow widths and degrades accessibility, since screen readers announce forced breaks instead of a natural pause between blocks. Separate thoughts belong in separate block elements, and vertical spacing belongs to CSS margins. Note that `<br>` is legitimate where the line break is part of the content itself (postal addresses, poems, lyrics), and this rule cannot tell those apart from presentational use: it flags every `<br>`. Leave it disabled if your templates render such content.
+`<br>` encodes presentation in markup: using it for spacing or to fake paragraphs breaks text reflow at narrow widths and degrades accessibility, since screen readers announce forced breaks instead of a natural pause between blocks. Use separate block elements for separate thoughts, and CSS margins for the spacing between them. `<br>` is legitimate where the line break is part of the content itself (postal addresses, poems, lyrics), but this rule cannot tell those apart from presentational use and flags every `<br>`, so leave it disabled if your templates render such content.
 
 Off by default; enable with `--include=H036`.
 
@@ -1047,9 +1047,7 @@ Please include a test to validate the rule.
 
 ## Custom Rules
 
-You can add custom rules just for your project by creating a `.djlint_rules.yaml` alongside
-your `pyproject.toml`. Rules can be added to this files and djLint will pick them up.
-A rules file in another location can be given with the `--rules` CLI option.
+You can add custom rules just for your project by creating a `.djlint_rules.yaml` alongside your `pyproject.toml`. Rules can be added to this files and djLint will pick them up. A rules file in another location can be given with the `--rules` CLI option.
 
 ### Pattern Rules
 
@@ -1075,20 +1073,16 @@ You can add rules that import and execute a custom python function:
     python_module: your_package.your_module
 ```
 
-The specified `python_module` must contain a `run()` function that will be executed on
-every checked file. It must accept the following arguments:
+The specified `python_module` must contain a `run()` function that will be executed on every checked file. It must accept the following arguments:
 
 ::: content
 
-- `rule`: The dict that represent your rule in `.djlint_rules.yaml`. You will typically
-  use this variable to access the rule name and message.
+- `rule`: The dict that represent your rule in `.djlint_rules.yaml`. You will typically use this variable to access the rule name and message.
 - `config`: The DJLint configuration object.
 - `html`: The full html content of the file.
 - `filepath`: Path to the file that we are currently checking.
-- `line_ends`: List of line `start` and `end` character position that you can use with
-  `djlint.lint.get_line()` to get line numbers from a character position. See the example.
-- `*args, **kwargs`: We might add other arguments in the future, so you should include
-  those two arguments to reduce the risk of failure on djLint upgrade.
+- `line_ends`: List of line `start` and `end` character position that you can use with `djlint.lint.get_line()` to get line numbers from a character position. See the example.
+- `*args, **kwargs`: We might add other arguments in the future, so you should include those two arguments to reduce the risk of failure on djLint upgrade.
   :::
 
 It must return a list of dict, one for each errors, with the following keys:

src/djlint/__init__.py

@@ -27,10 +27,10 @@
 def _fail_with_usage_code(func: Callable[..., None]) -> Callable[..., None]:
     """Keep djLint failing apart from djLint finding things.
 
-    An unhandled error used to reach the interpreter and exit 1, the same
-    code as "found lint errors" or "would reformat", so a pipeline could
-    not tell a crash from a normal failing run - a template djLint cannot
-    read looked exactly like a template it disliked. Failures now exit 2,
+    Left to reach the interpreter, an unhandled error exits 1, the same code
+    as "found lint errors" or "would reformat", and a pipeline cannot tell a
+    crash from a normal failing run: a template djLint cannot read looks
+    exactly like a template it disliked. So failures exit 2 instead,
     alongside the usage errors click already exits 2 for. The traceback is
     still printed, so bug reports lose nothing.
     """
@@ -49,7 +49,7 @@ def wrapper(*args: object, **kwargs: object) -> None:
             echo(
                 style(
                     "djLint failed and did not finish checking. This is not a"
-                    " clean run - report unexpected failures at"
+                    " clean run. Please report unexpected failures at"
                     " https://github.com/djlint/djLint/issues",
                     fg="red",
                     bold=True,

src/djlint/formatter/attributes.py

@@ -64,15 +64,12 @@ def has_unquoted_template_expression(attribute_group: str) -> bool:
 def count_object_properties(config: Config, value: str) -> int:
     """Count the number of properties in a JSON/JS object."""
     try:
-        # Try parsing as JSON first
         data = json.loads(value)
         return len(data)
     except json.JSONDecodeError:
-        # For JS objects, count property-like patterns
-        # Simple heuristic: count comma-separated properties
-        cleaned = config.format_attribute_js_json_string_pattern.sub(
-            "", value
-        )  # Remove strings
+        # not json, so fall back to counting comma separated properties.
+        # strings go first, or a comma inside one counts as a separator.
+        cleaned = config.format_attribute_js_json_string_pattern.sub("", value)
         return len(
             config.format_attribute_js_json_property_pattern.findall(cleaned)
         )
@@ -97,25 +94,21 @@ def format_json_with_indent(
     except json.JSONDecodeError:
         return value
     else:
-        # Use indent_size from config for JSON formatting
         indent_size = config.js_config.get("indent_size", 4)
         formatted = json.dumps(data, indent=indent_size)
-        # Add base_indent to each line (except first)
+        # json.dumps indents from column 0, so the attribute's own indentation
+        # goes in front of every line but the first, which follows the quote.
+        # the closing brace sits one level back from the properties.
         lines = formatted.split("\n")
         if len(lines) > 1:
             indented_lines = [lines[0]]
             for i, line in enumerate(lines[1:], 1):
-                if i == len(lines) - 1:  # Last line (closing brace)
-                    # Indent closing brace indent_size spaces less than properties
-                    # Content lines get: base_indent + json_indent_size
-                    # Closing should get: base_indent + json_indent_size - indent_size
+                if i == len(lines) - 1:
                     content_indent = base_indent + (" " * indent_size)
                     if len(content_indent) >= indent_size:
-                        closing_indent = content_indent[
-                            :-indent_size
-                        ]  # Remove indent_size spaces from content indent
+                        closing_indent = content_indent[:-indent_size]
                     else:
-                        closing_indent = base_indent  # Fallback to base_indent
+                        closing_indent = base_indent
                     indented_lines.append(closing_indent + line)
                 else:
                     indented_lines.append(base_indent + line)
@@ -131,48 +124,38 @@ def format_js_with_indent(config: Config, value: str, base_indent: str) -> str:
     )
 
     try:
-        # Use the same JS config as the main JS formatter
+        # the same config the main js formatter uses, except that the
+        # attribute's indentation is added below, so jsbeautifier adds none.
         js_config = dict(config.js_config)
-        js_config["indent_level"] = 0  # No extra indentation from jsbeautifier
+        js_config["indent_level"] = 0
 
         opts = BeautifierOptions(js_config)
         formatted: str = jsbeautifier.beautify(value, opts)
     except ValueError:
         return value
     else:
-        # Add base_indent to each line while preserving relative indentation
+        # keep jsbeautifier's relative indentation and put the attribute's own
+        # in front of it. the first line follows the quote, so it takes none.
         lines = formatted.split("\n")
         if len(lines) > 1:
-            indented_lines = [
-                lines[0].strip()
-            ]  # Remove jsbeautifier's indentation from first line
+            indented_lines = [lines[0].strip()]
 
             for i, line in enumerate(lines[1:], 1):
-                if not line.strip():  # Handle empty lines
+                if not line.strip():
                     indented_lines.append("")
                     continue
 
-                # Preserve the original jsbeautifier indentation structure
                 line_indent = len(line) - len(line.lstrip())
 
-                # Check if this is an object (starts and ends with braces)
                 is_object = value.strip().startswith(
                     "{"
                 ) and value.strip().endswith("}")
 
-                if (
-                    is_object and i == len(lines) - 1
-                ):  # Last line of object (closing brace)
-                    # Indent closing brace 2 spaces less than properties for objects
-                    # jsbeautifier already provides the correct line_indent difference
-                    # Content lines get: base_indent + (" " * line_indent_for_content) (e.g., 14 + 2 = 16)
-                    # Closing line gets: base_indent + (" " * line_indent_for_closing) (e.g., 14 + 0 = 14)
-                    # This naturally creates the 2-space difference we want
+                if is_object and i == len(lines) - 1:
                     indented_lines.append(
                         base_indent + (" " * line_indent) + line.strip()
                     )
                 else:
-                    # For general JS code or object properties, use full base_indent + jsbeautifier indent
                     indented_lines.append(
                         base_indent + (" " * line_indent) + line.strip()
                     )
@@ -434,18 +417,17 @@ def format_attributes(config: Config, html: str, token: TagToken) -> str:
             and VERBATIM_ATTRIBUTE_NEWLINE not in attrib_value
             and config.format_attribute_js_json_pattern.match(attrib_name)
         ):
-            # Check if it's an object or general JavaScript code
             if config.format_attribute_js_json_object_pattern.match(
                 attrib_value
             ):
-                # Skip objects with fewer than minimum properties
+                # an object short enough to read on one line is left there.
                 if (
                     count_object_properties(config, attrib_value)
                     >= config.format_attribute_js_json_min_props
                 ):
-                    # Format JSON objects first, then JavaScript objects
+                    # the value starts after the attribute name and its quote,
+                    # so that is where its content lines up.
                     if is_json_object(attrib_value):
-                        # Calculate proper base indentation for JSON content
                         json_base_indent = (
                             spacing
                             + (quote_length + len(attrib_name or "")) * " "
@@ -454,18 +436,15 @@ def format_attributes(config: Config, html: str, token: TagToken) -> str:
                             config, attrib_value, json_base_indent
                         )
                     else:
-                        # Calculate proper base indentation for JavaScript objects
                         js_base_indent = (
                             spacing
                             + (quote_length + len(attrib_name or "")) * " "
                         )
-                        # Format JavaScript objects
                         attrib_value = format_js_with_indent(
                             config, attrib_value, js_base_indent
                         )
             else:
-                # Format general JavaScript code (non-objects)
-                # Calculate base indentation for general JS code
+                # not an object, so js code with no property count to check.
                 js_code_base_indent = (
                     spacing + (quote_length + len(attrib_name or "")) * " "
                 )

src/djlint/formatter/class_attributes.py

@@ -38,7 +38,7 @@
 
 # attribute values that hold a token list or css, where a line break is
 # only formatting. everything else is kept as written: a value reaches the
-# page as it stands, so joining its lines changes the document - a `title`
+# page as it stands, so joining its lines changes the document. a `title`
 # tooltip loses a line, hyperscript ("_") loses a command separator, and a
 # `data-` value read by script comes back different.
 _JOINABLE_ATTRIBUTE_NAMES: Final = frozenset({
@@ -48,8 +48,8 @@
     "srcset",
     "style",
 })
-# of those, the ones whose edges mean nothing at all - a token list and
-# css - so joining their lines can close up rather than leave a space
+# of those, the ones whose edges mean nothing at all (a token list and
+# css), so joining their lines can close up rather than leave a space
 # behind. the rest are laid out by their own rules, which decide that.
 _TRIMMED_ATTRIBUTE_NAMES: Final = frozenset({"class", "style"})
 

src/djlint/formatter/condense.py

@@ -308,8 +308,8 @@ def _rendered_whitespace(text: str, left: str, right: str) -> str:
 
     Css collapses each run of space, tab and line break to one space, then
     drops that space where it falls against a line edge or against other
-    collapsible whitespace - the neighbour renders it instead. Whatever is
-    left over is layout this formatter owns rather than content, so it
+    collapsible whitespace, since the neighbour renders it instead. Whatever
+    is left over is layout this formatter owns rather than content, so it
     goes. Other whitespace (e.g. u+2005) is never collapsed or dropped.
 
     `left` and `right` are the single characters the whitespace sits

src/djlint/formatter/expand.py

@@ -367,8 +367,8 @@ def touches_rendered_content(index: int, *, back: bool) -> bool:
         """Whether rendered content runs right up to this position.
 
         Looks through tags that lay out nothing of their own, and through
-        the inside edge of a box - whitespace there is the edge of that
-        box's own content, so what lies beyond it is what would be parted.
+        the inside edge of a box, where whitespace is the edge of that box's
+        own content, so what lies beyond it is what would be parted.
         """
         while True:
             char = html[index - 1 : index] if back else html[index : index + 1]