Skip to content

Commit

Permalink
Inline example code in book
Browse files Browse the repository at this point in the history
This commit inlines some of the example code in the book.

This makes it easier to read book chapters using any text viewer, as
opposed to needing to use `mdbook`.
  • Loading branch information
chinedufn committed Apr 23, 2024
1 parent 75a1077 commit c3c950c
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 12 deletions.
85 changes: 77 additions & 8 deletions book/src/contributing/adding-compile-time-errors/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,25 @@ guide them towards the right fix.
For example, if a user wrote the following bridge module:

```rust
{{#include ../../../../crates/swift-bridge-macro/tests/ui/unrecognized-opaque-type-attribute.rs:mdbook-ui-test-example}}
#[swift_bridge::bridge]
mod ffi {
extern "Rust" {
#[swift_bridge(InvalidAttribute)]
type SomeType;
}
}

pub struct SomeType;
```

We would want to emit a compile time error along the lines of:

```sh
{{#include ../../../../crates/swift-bridge-macro/tests/ui/unrecognized-opaque-type-attribute.stderr}}
error: Unrecognized attribute "InvalidAttribute".
--> tests/ui/unrecognized-opaque-type-attribute.rs:8:24
|
8 | #[swift_bridge(InvalidAttribute)]
| ^^^^^^^^^^^^^^^^
```

This chapter shows how to add support for compile time errors.
Expand All @@ -30,9 +42,31 @@ Here are a few example parse errors:
```rust
// via: crates/swift-bridge-ir/src/errors/parse_error.rs

{{#include ../../../../crates/swift-bridge-ir/src/errors/parse_error.rs:mdbook-parse-error-enum}}

// ...
pub(crate) enum ParseError {
ArgsIntoArgNotFound {
func: ForeignItemFn,
missing_arg: Ident,
},
/// `extern {}`
AbiNameMissing {
/// `extern {}`
/// ------
extern_token: Token![extern],
},
/// `extern "Foo" {}`
AbiNameInvalid {
/// `extern "Foo" {}`
/// -----
abi_name: LitStr,
},
/// `fn foo (&self)`
/// ----
AmbiguousSelf { self_: Receiver },
/// fn foo (bar: &Bar);
/// If Bar wasn't declared using a `type Bar` declaration.
UndeclaredType { ty: Type },

// ... snip ...
}
```

Expand All @@ -42,9 +76,44 @@ Here are a few examples:
````rust
// via: crates/swift-bridge-ir/src/errors/parse_error.rs

{{#include ../../../../crates/swift-bridge-ir/src/errors/parse_error.rs:mdbook-parse-error-message}}

// ...
impl Into<syn::Error> for ParseError {
fn into(self) -> Error {
match self {
ParseError::AbiNameMissing {
extern_token: extern_ident,
} => Error::new_spanned(
extern_ident,
format!(
r#"extern modules must have their abi set to "Rust" or "Swift".
```
extern "Rust" {{ ... }}
extern "Swift" {{ ... }}
```
"#
),
),
ParseError::UndeclaredType { ty } => {
let ty_name = ty.to_token_stream().to_string();
let ty_name = ty_name.split_whitespace().last().unwrap();

let message = format!(
r#"Type must be declared with `type {}`.
"#,
ty_name
);
Error::new_spanned(ty, message)
}
ParseError::DeclaredBuiltInType { ty } => {
let message = format!(
r#"Type {} is already supported
"#,
ty.to_token_stream().to_string()
);
Error::new_spanned(ty, message)
}

// ... snip ...
}
}
}
````
Expand Down
4 changes: 0 additions & 4 deletions crates/swift-bridge-ir/src/errors/parse_error.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ use syn::{Error, FnArg, Item, Receiver};
use syn::{ForeignItemFn, ForeignItemType, LitStr};
use syn::{Token, Type};

// <!-- ANCHOR: mdbook-parse-error-enum -->
pub(crate) enum ParseError {
ArgsIntoArgNotFound {
func: ForeignItemFn,
Expand All @@ -28,7 +27,6 @@ pub(crate) enum ParseError {
/// fn foo (bar: &Bar);
/// If Bar wasn't declared using a `type Bar` declaration.
UndeclaredType { ty: Type },
// <!-- ANCHOR_END: mdbook-parse-error-enum -->
/// Declared a type that we already support.
/// Example: `type u32`
DeclaredBuiltInType { ty: ForeignItemType },
Expand Down Expand Up @@ -73,7 +71,6 @@ pub(crate) enum IdentifiableParseError {
MissingReturnType { fn_ident: Ident },
}

// <!-- ANCHOR: mdbook-parse-error-message -->
impl Into<syn::Error> for ParseError {
fn into(self) -> Error {
match self {
Expand Down Expand Up @@ -122,7 +119,6 @@ self: &mut SomeType
);
Error::new_spanned(ty, message)
}
// <!-- ANCHOR_END: mdbook-parse-error-message -->
ParseError::DeclaredBuiltInType { ty } => {
let message = format!(
r#"Type {} is already supported
Expand Down

0 comments on commit c3c950c

Please sign in to comment.