Improve dump-configuration with inline comments to explain each rule

[natikgadzhi]

Right now, swift-format dump-configuration is a great (and automatically up to date!) source of documentation on what rules are available:

swift-syntax internal/swift-format/omit-returns ≡2s
 ❯ swift-format dump-configuration
{
  "fileScopedDeclarationPrivacy" : {
    "accessLevel" : "private"
  },
  "indentation" : {
    "spaces" : 2
  },
  "indentConditionalCompilationBlocks" : true,
  "indentSwitchCaseLabels" : false,
  "lineBreakAroundMultilineExpressionChainComponents" : false,
  "lineBreakBeforeControlFlowKeywords" : false,
  "lineBreakBeforeEachArgument" : false,
  "lineBreakBeforeEachGenericRequirement" : false,
  "lineLength" : 100,
  "maximumBlankLines" : 1,
  "noAssignmentInExpressions" : {
    "allowedFunctions" : [
      "XCTAssertNoThrow"
    ]
  },
  "prioritizeKeepingFunctionOutputTogether" : false,
  "respectsExistingLineBreaks" : true,
  "rules" : {
    "AllPublicDeclarationsHaveDocumentation" : false,
    "AlwaysUseLowerCamelCase" : true,
    "AmbiguousTrailingClosureOverload" : true,
    "BeginDocumentationCommentWithOneLineSummary" : false,
    "DoNotUseSemicolons" : true,
    "DontRepeatTypeInStaticProperties" : true,
    "FileScopedDeclarationPrivacy" : true,
    "FullyIndirectEnum" : true,
    "GroupNumericLiterals" : true,
    "IdentifiersMustBeASCII" : true,
    "NeverForceUnwrap" : false,
    "NeverUseForceTry" : false,
    "NeverUseImplicitlyUnwrappedOptionals" : false,
    "NoAccessLevelOnExtensionDeclaration" : true,
    "NoAssignmentInExpressions" : true,
    "NoBlockComments" : true,
    "NoCasesWithOnlyFallthrough" : true,
    "NoEmptyTrailingClosureParentheses" : true,
    "NoLabelsInCasePatterns" : true,
    "NoLeadingUnderscores" : false,
    "NoParensAroundConditions" : true,
    "NoVoidReturnOnFunctionSignature" : true,
    "OmitExplicitReturns" : false,
    "OneCasePerLine" : true,
    "OneVariableDeclarationPerLine" : true,
    "OnlyOneTrailingClosureArgument" : true,
    "OrderedImports" : true,
    "ReturnVoidInsteadOfEmptyTuple" : true,
    "TypeNamesShouldBeCapitalized" : true,
    "UseEarlyExits" : false,
    "UseLetInEveryBoundCaseVariable" : true,
    "UseShorthandTypeNames" : true,
    "UseSingleLinePropertyGetter" : true,
    "UseSynthesizedInitializer" : true,
    "UseTripleSlashForDocumentationComments" : true,
    "UseWhereClausesInForLoops" : false,
    "ValidateDocumentationComments" : false
  },
  "spacesAroundRangeFormationOperators" : false,
  "tabWidth" : 8,
  "version" : 1
}

But, it's not clear what exactly each of those rules does. Luckily, opening the actual source code and the swift file responsible for each particular rule, each rule class seems to have a handy docc comment explaining what that rule does, including both what to expect from linting, and from formatting with that rule.

I think it would be great if dump-configuration also rendered some short version of that explanation in an inline-comment, maybe just 1-2 line, before each rule.

How would you feel about adding that? If the idea seems reasonable, I would be happy to explore a way to make that and keep that up to date.

UPD:

• DumpConfiguration.swift fetches the default Configuration() and then encodes it into json, which means it's very elegant and short, but less obvious how to inject comments into it.

[allevato]

JSON5 does support comments, and while it's possible to set allowsJSON5 on the JSONDecoder to allow it to parse JSON with comments successfully when it loads a configuration, there's no way to inject comments when encoding with JSONEncoder. So, doing this would require us to implement our own encoding logic for dump-configuration from scratch, which I don't think is really worth it.

Instead, the real issue is this parenthesized part:

Right now, swift-format dump-configuration is a great (and automatically up to date!) source of documentation

We need to do a much better job of keeping the documentation updated. DocC feels like it might at first be the obvious thing to reach for, because the rule documentation is represented as doc comments on the rules themselves, but there are some quirks about the rules (they're behind @_spi, they're not actually things we want users of swift-format as an API to see) that might make that more difficult. And we may want to use DocC for the actual public API, so I don't know if we should try to use the tool for both purposes.

Thinking about it more, we already have the generate-pipeline tool that uses SwiftSyntax to find all the rules. Maybe this should also scrape the rule documentation from each one and put it into a Markdown file to check in as part of the repo. Maybe it could even generate strings that could be used in a help description emitted by ArgumentParser, so that a formatter binary could stand alone.

[natikgadzhi]

I was doing some exploration yesterday night and got the late memo about json and comments. And yep, injecting comments into json AFTER it’s encoded sounds very hacky. I think the idea with generating a markdown article into a docc bundle is an interesting path that might work! Another idea: we could try and generate a Snippet and then use it in `@Snippet` directive in DocC. Since the snippet is just a swift file, we can easily do that in generate-pipeline, and then we have a guarantee that the DocC bundle has an up to date list of rules with comments for each. It feels like markdown is a better approach, we could also generate a docc table directive to make the list more readable and ahow default values. **UPD**: After looking at the `generate-pipeline`, I think it should be easy to generate the markdown file. We could do this a in a few ways: 1. Minimal: just generate a `Documentation/LintFormatRules.md` and link to it from `Documentation/Configuration.md`. We can also link to it from `swift-format --help` for now. 2. Better: convert the `Documentation` directory to a DocC bundle, and then work on publishing it on Swift Package Index. Let me work on pt 1 as a proof of concept, then proceed to pt2. @allevato, sounds good?