[Spagero763]

Updated the Clarity Formatter documentation with a comprehensive overview, integration methods, usage examples, and best practices for formatting Clarity smart contracts.

Description

Describe the changes that were made in this pull request. When possible start with the motivations behind the change.

[Copilot]

Pull request overview

This PR comprehensively revises the Clarity Formatter documentation, transforming it from a brief overview into an extensive guide with detailed examples, integration methods, and best practices for formatting Clarity smart contracts.

Changes:

• Expanded documentation from ~150 lines to ~878 lines with comprehensive coverage
• Added detailed sections on formatting philosophy, integration methods, and troubleshooting
• Included extensive code examples demonstrating before/after formatting and real-world usage
• Added CI/CD integration examples and team adoption guidelines

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The formatting configuration examples show two different file paths and formats (Clarinet.toml vs .clarinet/formatting.toml) with slightly different key naming conventions (indent-size vs indent_size). This inconsistency could confuse users about which file to use and which naming convention to follow. Consider clarifying which configuration file should be used or if both are valid options, and standardize the key naming convention.

Suggested change

	Commit formatting settings to version control:
	```toml
	# .clarinet/formatting.toml
	[style]
	indent_size = 2
	line_width = 100
	preserve_blank_lines = true
	Commit your formatter settings to version control by checking in your Clarinet.toml:
	```toml
	# Clarinet.toml
	[formatting]
	indent-size = 2
	line-width = 100
	preserve-blank-lines = true

[Copilot]

The pre-commit hook example automatically adds all files matching contracts/*.clar after formatting. This could inadvertently stage and commit files the developer didn't intend to include in the commit. Consider warning users about this behavior or suggesting they review the changes before the hook runs.

Suggested change

	# Add formatted files to commit
	git add contracts/*.clar
	# Review formatting changes
	git diff
	# Interactively stage only the formatted changes you want to commit
	git add -p contracts/*.clar

[Copilot]

The installation instructions for Linux show downloading 'clarinet-linux-x64.tar.gz' but the command doesn't specify where to move the binary after extraction. Users following these instructions may not know how to make clarinet available in their PATH. Consider adding the step to move the binary to a directory in PATH (e.g., sudo mv clarinet /usr/local/bin/).

Suggested change

	curl -L https://github.com/hirosystems/clarinet/releases/latest/download/clarinet-linux-x64.tar.gz | tar xz
	curl -L https://github.com/hirosystems/clarinet/releases/latest/download/clarinet-linux-x64.tar.gz | tar xz
	# Move the extracted binary into a directory on your PATH
	sudo mv clarinet /usr/local/bin/

[Copilot]

The YAML configuration uses preserve_blank_lines = true with an equals sign in a TOML file example. TOML syntax uses equals signs, not colons like YAML. However, this creates inconsistency with the naming convention used (underscores vs hyphens) compared to the earlier example. Ensure the syntax and naming conventions are consistent across all configuration examples.

Suggested change

	indent_size = 2
	line_width = 100
	preserve_blank_lines = true
	indent-size = 2
	line-width = 100
	preserve-blank-lines = true

[Copilot]

The comparison table header "Accuracy" would be clearer than "Error-prone" since the values "Prone to human error" vs "Deterministic and error-free" already indicate the error-prone nature. This makes the table more readable and less confusing.

[Copilot]

The example shows types: [clarity] in the pre-commit configuration, but this file type may not be recognized by the pre-commit framework by default. Consider verifying this is a valid type identifier or providing additional setup instructions if custom type detection is needed.

Suggested change

	types: [clarity]
	files: \.clar$

[Copilot]

The documentation mentions that the @format-ignore-start and @format-ignore-end directives exist for multi-line ignore blocks, but doesn't clarify if these are actually supported features or just proposed syntax. If these directives are not yet implemented, this could mislead users. Consider verifying this functionality exists or marking it as a proposed feature.

[Copilot]

The example shows formatting with 1-9 instead of u1-u9 for unsigned integers in the list. In Clarity, numeric literals need the 'u' prefix for unsigned integers. This syntax error could confuse users learning the language.

Suggested change

	1 2 3 ;; Custom spacing preserved
	4 5 ))
	u1 u2 u3 ;; Custom spacing preserved
	u4 u5 ))

[eric-stacks]

this revision to the existing Clarity Formatter guide is long winded and a bit verbose. there's also many errors in it. the AI generated format and content is also a bit too much. this revision also removes the existing cover image.

the current guide is much more succinct and concise.