Skip to content

Commit 3fb6a58

Browse files
luisfi-devluisfi-dev
committed
Crate documentation
1 parent d2efed9 commit 3fb6a58

3 files changed

Lines changed: 213 additions & 14 deletions

File tree

‎README.md‎

Lines changed: 106 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,110 @@
11
# `error-stack-macros2`
22

3-
Community-made procedural macros for [`error-stack`](https://crates.io/crates/error-stack).
3+
[![crates.io latest version](https://img.shields.io/crates/v/error-stack-macros2?label=version&logo=rust)](https://crates.io/crates/error-stack-macros2)
4+
[![crates.io downloads](https://img.shields.io/crates/d/error-stack-macros2)](https://crates.io/crates/error-stack-macros2)
5+
[![Tests status](https://img.shields.io/github/actions/workflow/status/LuisFerLCC/error-stack-macros2/test.yml?branch=master&label=tests)](https://github.com/LuisFerLCC/error-stack-macros2/actions/workflows/test.yml)
6+
[![Contributor Covenant Code of Conduct](https://img.shields.io/badge/Contributor%20Covenant-3.0-5e0d73?logo=contributorcovenant)](https://github.com/LuisFerLCC/error-stack-macros2/blob/master/.github/CODE_OF_CONDUCT.md)
47

5-
**NOTE 1:** This crate is not affiliated with the official [`error-stack`](https://crates.io/crates/error-stack)
6-
crate or its maintainers.
8+
Community-made procedural macros for [`error-stack`].
79

8-
**NOTE 2:** This crate is currently empty and under development. This version
9-
(`0.0.0-reserved`) only reserves the crate name on crates.io for future use.
10+
## Example
11+
12+
Here is the same example shown in the [`error-stack`] `README`, modified to
13+
use the macros provided by this crate:
14+
15+
```rust
16+
use error_stack::{Report, ResultExt};
17+
use error_stack_macros2::Error;
18+
19+
#[derive(Debug, Error)]
20+
#[display("invalid experiment description")]
21+
struct ParseExperimentError;
22+
23+
fn parse_experiment(
24+
description: &str
25+
) -> Result<(u64, u64), Report<ParseExperimentError>> {
26+
let value = description
27+
.parse::<u64>()
28+
.attach_with(|| {
29+
format!("{description:?} could not be parsed as experiment")
30+
})
31+
.change_context(ParseExperimentError)?;
32+
33+
Ok((value, 2 * value))
34+
}
35+
36+
#[derive(Debug, Error)]
37+
#[display("experiment error: could not run experiment")]
38+
struct ExperimentError;
39+
40+
fn start_experiments(
41+
experiment_ids: &[usize],
42+
experiment_descriptions: &[&str],
43+
) -> Result<Vec<u64>, Report<ExperimentError>> {
44+
let experiments = experiment_ids
45+
.iter()
46+
.map(|exp_id| {
47+
let description = experiment_descriptions
48+
.get(*exp_id)
49+
.ok_or_else(|| {
50+
Report::new(ExperimentError)
51+
.attach(format!(
52+
"experiment {exp_id} has no valid description")
53+
)
54+
})?;
55+
56+
let experiment = parse_experiment(description)
57+
.attach(format!("experiment {exp_id} could not be parsed"))
58+
.change_context(ExperimentError)?;
59+
60+
Ok(move || experiment.0 * experiment.1)
61+
})
62+
.collect::<Result<Vec<_>, Report<ExperimentError>>>()
63+
.attach("unable to set up experiments")?;
64+
65+
Ok(experiments.iter().map(|experiment| experiment()).collect())
66+
}
67+
68+
let experiment_ids = &[0, 2];
69+
let experiment_descriptions = &["10", "20", "3o"];
70+
let err = start_experiments(experiment_ids, experiment_descriptions)
71+
.unwrap_err();
72+
73+
assert_eq!(err.to_string(), "experiment error: could not run experiment");
74+
```
75+
76+
## Support
77+
78+
Need help using `error-stack-macros2`? Don't hesitate to reach out on
79+
[GitHub Discussions](https://github.com/LuisFerLCC/error-stack-macros2/discussions/categories/q-a)!
80+
81+
## Links
82+
83+
- [Documentation]
84+
- [GitHub](https://github.com/LuisFerLCC/error-stack-macros2)
85+
- [crates.io](https://crates.io/crates/error-stack-macros2)
86+
87+
## Contributing
88+
89+
Before creating an issue, please consider the following:
90+
91+
- Refer to the [documentation] to
92+
make sure the error is actually a bug and not a mistake of your own.
93+
- Make sure the issue hasn't already been reported or suggested.
94+
- Please report any security vulnerabilities privately through
95+
[Security Advisories](https://github.com/LuisFerLCC/error-stack-macros2/security/advisories/new).
96+
- After following these steps, you can file an issue using one of our
97+
[templates](https://github.com/LuisFerLCC/error-stack-macros2/issues/new/choose).
98+
Please make sure to follow our
99+
[Code of Conduct](https://github.com/LuisFerLCC/error-stack-macros2/blob/master/.github/CODE_OF_CONDUCT.md).
100+
- If you wish to [submit a pull request](https://github.com/LuisFerLCC/error-stack-macros2/compare)
101+
alongside your issue, please follow our
102+
[contribution guidelines](https://github.com/LuisFerLCC/error-stack-macros2/blob/master/.github/CONTRIBUTING.md).
103+
104+
## Disclaimer
105+
106+
This crate is not affiliated with the official [`error-stack`] crate or its
107+
maintainers.
108+
109+
[`error-stack`]: https://crates.io/crates/error-stack
110+
[documentation]: https://docs.rs/error-stack-macros2

‎impl/Cargo.toml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@ description = "Community-made procedural macros for error-stack."
88
readme = "../README.md"
99
repository = "https://github.com/LuisFerLCC/error-stack-macros2"
1010
license = "Apache-2.0"
11-
keywords = ["error", "errorstack", "macros", "proc-macro", "no_std"]
12-
categories = ["development-tools", "no-std", "rust-patterns"]
11+
keywords = ["error", "errorstack", "error-handling", "macros", "proc-macro"]
12+
categories = ["development-tools", "rust-patterns"]
1313

1414
[lib]
1515
proc-macro = true

‎impl/src/lib.rs‎

Lines changed: 105 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,111 @@
1-
//! Community-made procedural macros for
2-
//! [`error-stack`](https://crates.io/crates/error-stack).
1+
//! [![crates.io latest version](https://img.shields.io/crates/v/error-stack-macros2?label=version&logo=rust)](https://crates.io/crates/error-stack-macros2)
2+
//! [![crates.io downloads](https://img.shields.io/crates/d/error-stack-macros2)](https://crates.io/crates/error-stack-macros2)
3+
//! [![Tests status](https://img.shields.io/github/actions/workflow/status/LuisFerLCC/error-stack-macros2/test.yml?branch=master&label=tests)](https://github.com/LuisFerLCC/error-stack-macros2/actions/workflows/test.yml)
4+
//! [![Contributor Covenant Code of Conduct](https://img.shields.io/badge/Contributor%20Covenant-3.0-5e0d73?logo=contributorcovenant)](https://github.com/LuisFerLCC/error-stack-macros2/blob/master/.github/CODE_OF_CONDUCT.md)
35
//!
4-
//! **NOTE 1:** This crate is not affiliated with the official
5-
//! [`error-stack`](https://crates.io/crates/error-stack) crate or its
6+
//! Community-made procedural macros for [`error-stack`].
7+
//!
8+
//! # Example
9+
//!
10+
//! Here is the same example shown in the [`error-stack`] `README`, modified to
11+
//! use the macros provided by this crate:
12+
//!
13+
//! ```rust
14+
//! use error_stack::{Report, ResultExt};
15+
//! use error_stack_macros2::Error;
16+
//!
17+
//! #[derive(Debug, Error)]
18+
//! #[display("invalid experiment description")]
19+
//! struct ParseExperimentError;
20+
//!
21+
//! fn parse_experiment(
22+
//! description: &str
23+
//! ) -> Result<(u64, u64), Report<ParseExperimentError>> {
24+
//! let value = description
25+
//! .parse::<u64>()
26+
//! .attach_with(|| {
27+
//! format!("{description:?} could not be parsed as experiment")
28+
//! })
29+
//! .change_context(ParseExperimentError)?;
30+
//!
31+
//! Ok((value, 2 * value))
32+
//! }
33+
//!
34+
//! #[derive(Debug, Error)]
35+
//! #[display("experiment error: could not run experiment")]
36+
//! struct ExperimentError;
37+
//!
38+
//! fn start_experiments(
39+
//! experiment_ids: &[usize],
40+
//! experiment_descriptions: &[&str],
41+
//! ) -> Result<Vec<u64>, Report<ExperimentError>> {
42+
//! let experiments = experiment_ids
43+
//! .iter()
44+
//! .map(|exp_id| {
45+
//! let description = experiment_descriptions
46+
//! .get(*exp_id)
47+
//! .ok_or_else(|| {
48+
//! Report::new(ExperimentError)
49+
//! .attach(format!(
50+
//! "experiment {exp_id} has no valid description")
51+
//! )
52+
//! })?;
53+
//!
54+
//! let experiment = parse_experiment(description)
55+
//! .attach(format!("experiment {exp_id} could not be parsed"))
56+
//! .change_context(ExperimentError)?;
57+
//!
58+
//! Ok(move || experiment.0 * experiment.1)
59+
//! })
60+
//! .collect::<Result<Vec<_>, Report<ExperimentError>>>()
61+
//! .attach("unable to set up experiments")?;
62+
//!
63+
//! Ok(experiments.iter().map(|experiment| experiment()).collect())
64+
//! }
65+
//!
66+
//! let experiment_ids = &[0, 2];
67+
//! let experiment_descriptions = &["10", "20", "3o"];
68+
//! let err = start_experiments(experiment_ids, experiment_descriptions)
69+
//! .unwrap_err();
70+
//!
71+
//! assert_eq!(err.to_string(), "experiment error: could not run experiment");
72+
//! ```
73+
//!
74+
//! # Support
75+
//!
76+
//! Need help using `error-stack-macros2`? Don't hesitate to reach out on
77+
//! [GitHub Discussions](https://github.com/LuisFerLCC/error-stack-macros2/discussions/categories/q-a)!
78+
//!
79+
//! # Links
80+
//!
81+
//! - [Documentation]
82+
//! - [GitHub](https://github.com/LuisFerLCC/error-stack-macros2)
83+
//! - [crates.io](https://crates.io/crates/error-stack-macros2)
84+
//!
85+
//! # Contributing
86+
//!
87+
//! Before creating an issue, please consider the following:
88+
//!
89+
//! - Refer to the [documentation] to
90+
//! make sure the error is actually a bug and not a mistake of your own.
91+
//! - Make sure the issue hasn't already been reported or suggested.
92+
//! - Please report any security vulnerabilities privately through
93+
//! [Security Advisories](https://github.com/LuisFerLCC/error-stack-macros2/security/advisories/new).
94+
//! - After following these steps, you can file an issue using one of our
95+
//! [templates](https://github.com/LuisFerLCC/error-stack-macros2/issues/new/choose).
96+
//! Please make sure to follow our
97+
//! [Code of Conduct](https://github.com/LuisFerLCC/error-stack-macros2/blob/master/.github/CODE_OF_CONDUCT.md).
98+
//! - If you wish to [submit a pull request](https://github.com/LuisFerLCC/error-stack-macros2/compare)
99+
//! alongside your issue, please follow our
100+
//! [contribution guidelines](https://github.com/LuisFerLCC/error-stack-macros2/blob/master/.github/CONTRIBUTING.md).
101+
//!
102+
//! # Disclaimer
103+
//!
104+
//! This crate is not affiliated with the official [`error-stack`] crate or its
6105
//! maintainers.
7106
//!
8-
//! **NOTE 2:** This crate is currently empty and under development. This
9-
//! version (`0.0.0-reserved`) only reserves the crate name on crates.io for
10-
//! future use.
107+
//! [`error-stack`]: https://crates.io/crates/error-stack
108+
//! [documentation]: https://docs.rs/error-stack-macros2
11109
12110
use proc_macro::TokenStream;
13111
use quote::quote;

0 commit comments

Comments
 (0)