fix: usage of backticks in documentation comments

[agarmu]

Idiomatic Rust code's usage of backticks in documentation comments requires that names of terms with semantic meaning be surrounded by backticks and requires that backtick usage be balanced (per lint clippy::doc-markdown). This pull request ensures adherence to these standards across the codebase.

[kdkasad]

Thanks!

The unbalanced backticks were intentional; see the comment there. Everything else looks good.

Also, you mentioned a clippy warning. Is there an additional clippy configuration that should be added to the CI workflow in order to detect problems in doc comments? cargo clippy and cargo doc both don't complain about anything currently.

[agarmu]

Thanks!

The unbalanced backticks were intentional; see the comment there. Everything else looks good.

Also, you mentioned a clippy warning. Is there an additional clippy configuration that should be added to the CI workflow in order to detect problems in doc comments? cargo clippy and cargo doc both don't complain about anything currently.

By default, clippy only has a minimal set of sensible lints that it enforces (if you are not following those defaults, your code is probably horribly unidiomatic). There are many more warnings that can be enabled, grouped into certain categories (cf. -Wall and -Wextra). At the extreme end of the set of warnings would be something like this:

$ cargo clippy --all -- -W clippy::all -W clippy::pedantic -W clippy::restriction

but this is beyond excessive and includes lints which contradict one another; a more measured approach is necessary to get any work done. To set the standards for a particular project (so linting can be done by just running cargo clippy rather than specifying flags), one can include something like

#![warn(clippy::pedantic)]

at the top level of your project. I would strongly recommend giving this webpage a read-through to understand how clippy works (and follow it up with this one if you have time).