Skip to content

Commit 934958e

Browse files
committed
Add a Library rules section, starting with Flogger
The formatter carries a few layout rules for particular libraries, and none of them was documented anywhere, upstream included. The new section says what a library rule is, lists the ones that exist and tells how to propose another. The Flogger page shows the same log statement formatted by the default rules and by the rule, and spells out the three conditions under which the rule applies. Both outputs are real: the first comes from a build with the rule switched off, the second matches release 2.98.0.1.
1 parent bea8d76 commit 934958e

3 files changed

Lines changed: 52 additions & 0 deletions

File tree

‎docs/library-rules/flogger.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Flogger
2+
3+
A [Flogger](https://github.com/google/flogger) log statement keeps the logger and its fluent calls
4+
on one line, and only the arguments of `log(` wrap.
5+
6+
``` java title="Default rules"
7+
logger.atInfo()
8+
.withCause(e)
9+
.log("Cleaner finished. Deleted %d sessions, names: %s", deleted.size(), deletedNames);
10+
```
11+
12+
``` java title="With the Flogger rule"
13+
logger.atInfo().withCause(e).log(
14+
"Cleaner finished. Deleted %d sessions, names: %s", deleted.size(), deletedNames);
15+
```
16+
17+
## When it applies
18+
19+
All three have to hold. Otherwise the statement is formatted by the default rules.
20+
21+
- The chain ends with a call to `log`.
22+
- Every call in the chain is one of Flogger's: `at`, `atConfig`, `atDebug`, `atFine`, `atFiner`,
23+
`atFinest`, `atInfo`, `atWarning`, `atSevere`, `atMostEvery`, `every`, `perUnique`, `withCause`,
24+
`withStackTrace`, `log`, `logVarargs`.
25+
- The chain starts with a plain name, such as `logger`. `this.logger` does not count.
26+
27+
The rule comes from google-java-format, where it was added in 2018.

‎docs/library-rules/index.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Library rules
2+
3+
open-java-format has one style and no options. A few libraries are written so that a chain of calls
4+
reads as one phrase, and the general rule of one call per line cuts that phrase apart. For those
5+
libraries the formatter carries a rule of its own.
6+
7+
A library rule is built in, so there is nothing to configure. It goes by method names, because the
8+
formatter sees syntax and not types, and it leaves alone any code that does not match.
9+
10+
| Library | What the rule does |
11+
| --- | --- |
12+
| [Flogger](flogger.md) | Keeps the logger and its fluent calls on one line in front of `log(` |
13+
14+
## Proposing a rule
15+
16+
[Open an issue](https://github.com/openjavaformat/open-java-format/issues/new) with the library, a
17+
piece of code as it is formatted today, and the way it should look. The proposal for
18+
[Mutiny](https://github.com/openjavaformat/open-java-format/issues/25) shows what that takes.
19+
20+
A new rule changes how existing code is formatted, so it ships only in a release that is allowed to
21+
change output.

‎zensical.toml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,10 @@ nav = [
2525
{ "GitHub Action and pre-commit" = "get-started/github-actions.md" },
2626
] },
2727
{ "AI agents" = "ai-agents.md" },
28+
{ "Library rules" = [
29+
"library-rules/index.md",
30+
{ "Flogger" = "library-rules/flogger.md" },
31+
] },
2832
{ "Manifesto" = "manifesto.md" },
2933
]
3034

0 commit comments

Comments
 (0)