Skip to content

Commit 407ec13

Browse files
committed
docs: add more code style guide references
1 parent b9667aa commit 407ec13

File tree

1 file changed

+21
-0
lines changed

1 file changed

+21
-0
lines changed

STYLE.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,13 @@ This allows to run `RUST_BACKTRACE=1 cargo test`
8484
and get a backtrace with line numbers in resultified tests
8585
which return `anyhow::Result`.
8686

87+
`unwrap` and `expect` are not used in the library
88+
because panics are difficult to debug on user devices.
89+
However, in the tests `.expect` may be used.
90+
Follow
91+
<https://doc.rust-lang.org/core/error/index.html#common-message-styles>
92+
for `.expect` message style.
93+
8794
## Logging
8895

8996
For logging, use `info!`, `warn!` and `error!` macros.
@@ -96,3 +103,17 @@ Format anyhow errors with `{:#}` to print all the contexts like this:
96103
```
97104
error!(context, "Failed to set selfavatar timestamp: {err:#}.");
98105
```
106+
107+
## Documentation comments
108+
109+
All public modules, methods and fields should be documented.
110+
This is checked by [`missing_docs`](https://doc.rust-lang.org/rustdoc/lints.html#missing_docs) lint.
111+
112+
Private items do not have to be documented,
113+
but CI uses `cargo doc --document-private-items`
114+
to build the documentation,
115+
so it is preferred that new items
116+
are documented.
117+
118+
Follow Rust guidelines for the documentation comments:
119+
<https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#summary-sentence>

0 commit comments

Comments
 (0)