Skip to content

Allow /** */ block doc comments and add bundled-config integration tests - #2

Merged
0xLeif merged 7 commits into
mainfrom
config/allow-block-doc-comments
Apr 25, 2026
Merged

Allow /** */ block doc comments and add bundled-config integration tests#2
0xLeif merged 7 commits into
mainfrom
config/allow-block-doc-comments

Conversation

@0xLeif

@0xLeif 0xLeif commented Apr 24, 2026

Copy link
Copy Markdown
Owner

Summary

  • Config: disable UseTripleSlashForDocumentationComments so swift-format no longer rewrites /** ... */ block doc comments to ///. 0xLeif style uses /// for short (1-2 line) docs and /** */ for longer (3+ line) docs.
  • Config: enable lineBreakBeforeEachArgument so partially-split argument lists become one-arg-per-line.
  • Tests: add 98 integration tests (35 format + 33 lint + 7 disabled-rule negatives + 1 stress + helpers) that pipe horrible Swift code through the real swift-format binary using the bundled .swift-format.json and verify the exact behavior shipped to plugin users.
  • Sources: reformat Plugin.swift and ProtocolHandler.swift with the bundled config so the project dogfoods its own style.

Test coverage

Format mode — tabs/2-space → 4-space, Allman → K&R, blank-line collapse, partially-split args → one-per-line, import sort + @testable grouping, multi-line trailing commas, semicolon splitting, empty closure parens, var-per-line, fallthrough merge, hybrid doc-comment style, idempotence, mixed indentation, trailing whitespace, switch-case label alignment, conditional-compilation indent, range-operator spacing, EOL comment spacing, single-line getter shorthand, OneCasePerLine splits (raw + associated), generic signature wrap, multi-line string preservation, explicit-return preservation, binary operator/colon/comma/paren spacing, trailing-closure call-site cleanup, capture lists, async let, willSet/didSet, property wrappers, some/any, @resultBuilder, #available, single-shot stress test.

Lint mode — force unwrap, force try, force cast, IUO, shorthand types, block comments (with /** */ negative), naming, access-on-extension, parens around conditions, void return, ordered imports, semicolons, forEach, GroupNumericLiterals (decimal + hex), UseSingleLinePropertyGetter, DontRepeatTypeInStaticProperties, UseSynthesizedInitializer, UseLetInEveryBoundCaseVariable, UseExplicitNilCheckInConditions, ReturnVoidInsteadOfEmptyTuple, FullyIndirectEnum, OneCasePerLine, IdentifiersMustBeASCII, NoAssignmentInExpressions, AvoidRetroactiveConformances, AmbiguousTrailingClosureOverload, NoPlaygroundLiterals, NoLabelsInCasePatterns.

Negative cases — confirms NoLeadingUnderscores, OmitExplicitReturns, UseEarlyExits, UseWhereClausesInForLoops, AllPublicDeclarationsHaveDocumentation, ValidateDocumentationComments, BeginDocumentationCommentWithOneLineSummary all stay quiet on input that would otherwise trigger them.

Impact across 0xLeif repos (block-doc-comment rule disabled)

Repo Before After
AppState 75 3
Waiter 31 0
Later 66 62
Fork 43 43
Cache 721 627

Test plan

  • swift build passes
  • swift test passes (98 tests across 5 suites)

🤖 Generated with Claude Code

0xLeif and others added 2 commits April 24, 2026 07:25
Sets lineBreakBeforeEachArgument=true so long function declarations
and call sites break one parameter per line, matching the CorvidLabs
style guide example. Short calls stay inline.

Verified against 0xLeif/AppState (newest, 36 files): only 1 file
needed wrapping changes. Older repos (Cache, Fork, Later, Waiter)
receive legitimate style enforcement (triple-slash docs, trailing
whitespace, case binding style).

Also marks protocol-mode end-to-end verification complete in
specs/format/tasks.md and specs/lint/tasks.md after confirming
`fledge swift-format`, `--lint`, and `--check` all work via the
installed plugin.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Disables UseTripleSlashForDocumentationComments so swift-format no longer
converts /** ... */ block doc comments to ///. Per 0xLeif's style: /// for
1-2 line doc comments, /** */ for 3+ line doc comments. The rule is binary
and can't enforce the length threshold, but turning it off stops the
formatter from rewriting the longer blocks.

Impact across 0xLeif repos:
- AppState: 75 -> 3 findings
- Waiter: 31 -> 0
- Later: 66 -> 62
- Fork: unchanged (no block comments)
- Cache: 721 -> 627

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the Swift formatting configuration by enabling line breaks before each argument and disabling triple-slash documentation comments. It also marks the end-to-end verification of the Fledge protocol mode as complete in the task documentation for both formatting and linting. Feedback indicates that the change to argument line breaks is undocumented and potentially significant, and it raises concerns about marking protocol verification as complete while automated integration tests remain outstanding.

"lineBreakAroundMultilineExpressionChainComponents" : false,
"lineBreakBeforeControlFlowKeywords" : false,
"lineBreakBeforeEachArgument" : false,
"lineBreakBeforeEachArgument" : true,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The change to lineBreakBeforeEachArgument is not documented in the PR summary. This setting significantly alters how function arguments are formatted across the project by forcing each argument to a new line when wrapping. If this change was unintentional, it should be reverted; otherwise, it should be explicitly mentioned in the description to ensure all stakeholders are aware of the style change.

Comment thread specs/format/tasks.md
- [x] Embed bundled .swift-format.json as resource
- [ ] Add integration test with real swift-format binary
- [ ] Verify Fledge protocol mode works end-to-end
- [x] Verify Fledge protocol mode works end-to-end

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The task 'Verify Fledge protocol mode works end-to-end' is marked as complete, yet the 'Add integration test' task remains open. Relying on manual verification without automated integration tests for the protocol mode increases the risk of future regressions.

Comment thread specs/lint/tasks.md
- [x] Implement --check alias for --lint --strict
- [ ] Add integration test with real swift-format binary
- [ ] Verify Fledge protocol mode works end-to-end
- [x] Verify Fledge protocol mode works end-to-end

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The task 'Verify Fledge protocol mode works end-to-end' is marked as complete, yet the 'Add integration test' task remains open. Relying on manual verification without automated integration tests for the protocol mode increases the risk of future regressions.

0xLeif and others added 5 commits April 25, 2026 09:57
Drives the real swift-format binary against horrible input via stdin
so we verify the actual behavior shipped to plugin users. Covers
indentation, brace style, blank lines, argument wrapping, imports,
trailing commas, semicolons, closure parens, var-per-line, fallthrough
merging, hybrid doc-comment style, and idempotence in format mode;
plus type/var naming, force unwrap/try, IUO, shorthand types, block
comments (with /** */ negative case), access-on-extension, parens
around conditions, void return, ordered imports, and empty findings
on clean source in lint mode.

Reformats Plugin.swift and ProtocolHandler.swift with the bundled
config so the project dogfoods its own style.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Format mode now also covers mixed indentation, trailing whitespace,
switch-case label alignment, conditional compilation indent, range
operator spacing, end-of-line comment spacing, single-line property
getter shorthand, OneCasePerLine splits (raw + associated),
multi-line generic signature wrap, multi-line string preservation,
and explicit-return preservation.

Lint mode now also covers forEach, GroupNumericLiterals (decimal +
hex), UseSingleLinePropertyGetter, DontRepeatTypeInStaticProperties,
UseSynthesizedInitializer, UseLetInEveryBoundCaseVariable,
UseExplicitNilCheckInConditions, ReturnVoidInsteadOfEmptyTuple,
FullyIndirectEnum, OneCasePerLine, IdentifiersMustBeASCII,
NoAssignmentInExpressions, AvoidRetroactiveConformances, and
negative cases for NoLeadingUnderscores, OmitExplicitReturns,
UseEarlyExits, and UseWhereClausesInForLoops.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Format mode now also covers binary operator spacing, colon spacing,
comma spacing, paren-interior whitespace, trailing-closure call site
cleanup, capture lists, async let, willSet/didSet, and property
wrapper attributes.

Lint mode now reports force cast (as!) under NeverForceUnwrap and
verifies try? and as? do not trigger force-unwrap rules.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Verifies some/any/@resultBuilder/#available stay intact, plus a
single-shot stress test that combines unsorted imports, Allman
braces, mixed tab/space indent, bad colon/comma/operator spacing,
parens around conditions, semicolons, and multi-var declarations
into one input and asserts the fully cleaned output.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reports AmbiguousTrailingClosureOverload, NoPlaygroundLiterals, and
NoLabelsInCasePatterns when their respective triggers appear; verifies
disabled rules (AllPublicDeclarationsHaveDocumentation,
ValidateDocumentationComments, BeginDocumentationCommentWithOneLineSummary)
do not fire on input that would otherwise violate them.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@0xLeif 0xLeif changed the title Allow /** */ block doc comments Allow /** */ block doc comments and add bundled-config integration tests Apr 25, 2026
@0xLeif
0xLeif merged commit d7b79af into main Apr 25, 2026
1 check passed
@0xLeif
0xLeif deleted the config/allow-block-doc-comments branch April 25, 2026 16:42
@0xLeif 0xLeif mentioned this pull request Apr 25, 2026
1 task
0xLeif added a commit that referenced this pull request Apr 25, 2026
Reflects PR #2 config changes (UseTripleSlashForDocumentationComments
disabled, lineBreakBeforeEachArgument enabled) which are user-facing
behavior changes, plus the integration test suite expansion and
plugin source dogfooding from PRs #2 and #3.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant