Document modified configurations used for examples

[SimplyDanny]

Example:

for user in users {
  if user.id == 1 { return true }
}

//
// allow_for_as_filter: true
//

[SwiftLintBot]

	17 Messages
:book:	Linting Aerial with this PR took 0.98s vs 1.0s on main (2% faster)
:book:	Linting Alamofire with this PR took 1.36s vs 1.36s on main (0% slower)
:book:	Linting Brave with this PR took 8.05s vs 8.07s on main (0% faster)
:book:	Linting DuckDuckGo with this PR took 4.48s vs 4.5s on main (0% faster)
:book:	Linting Firefox with this PR took 11.37s vs 11.4s on main (0% faster)
:book:	Linting Kickstarter with this PR took 10.11s vs 10.08s on main (0% slower)
:book:	Linting Moya with this PR took 0.56s vs 0.56s on main (0% slower)
:book:	Linting NetNewsWire with this PR took 2.77s vs 2.76s on main (0% slower)
:book:	Linting Nimble with this PR took 0.81s vs 0.81s on main (0% slower)
:book:	Linting PocketCasts with this PR took 8.7s vs 8.81s on main (1% faster)
:book:	Linting Quick with this PR took 0.45s vs 0.46s on main (2% faster)
:book:	Linting Realm with this PR took 5.05s vs 5.05s on main (0% slower)
:book:	Linting Sourcery with this PR took 2.53s vs 2.53s on main (0% slower)
:book:	Linting Swift with this PR took 4.92s vs 4.94s on main (0% faster)
:book:	Linting VLC with this PR took 1.33s vs 1.34s on main (0% faster)
:book:	Linting Wire with this PR took 19.25s vs 19.28s on main (0% faster)
:book:	Linting WordPress with this PR took 14.32s vs 14.32s on main (0% slower)

Generated by :no_entry_sign: Danger

[SimplyDanny]

@mildm8nnered: I would like to hear your opinion on this. Is the presentation style clear enough?

[mildm8nnered]

@mildm8nnered: I would like to hear your opinion on this. Is the presentation style clear enough?

So I think it's a matter of taste, but I'd probably put the context before the example, so something like this:

// allow_for_as_filter: true
for user in users {
  if user.id == 1 { return true }
}

although that could collide with swift documentation comments in some cases ...

I guess there's also a bit of a risk that people might think these are directives like // swiftlint:disable somehow, and end up pasting them into their own code.

[SimplyDanny]

@mildm8nnered: I would like to hear your opinion on this. Is the presentation style clear enough?

So I think it's a matter of taste, but I'd probably put the context before the example, so something like this:

// allow_for_as_filter: true
for user in users {
  if user.id == 1 { return true }
}

although that could collide with swift documentation comments in some cases ...

I guess there's also a bit of a risk that people might think these are directives like // swiftlint:disable somehow, and end up pasting them into their own code.

All the variants I can think of are not optimal. I went with your suggestion to have the configuration first. There is an empty line between them and the code. That should be a clear enough separation. Example:

//
// allow_for_as_filter: true
//

for user in users {
  if user.id == 1 { return true }
}

The documentation is (hopefully) not something people rely upon as an API, so we can update it once we come up with a better idea later.