Add documentation on type borrowing

This commit is contained in:
iinuwa 2020-12-28 17:21:42 -06:00 committed by GitHub
parent 68ba3049ea
commit 2686a3ecc0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -186,6 +186,62 @@ guidelines:
- If you're not sure what to name it, pick any name and we can help you
with it.
### Borrowing Request Types
In order to reduce the number of `.clone()`s necessary to send requests
to a server, we support borrowed types for request types. (We hope to support
borrowing in response types sometime, but that is dependent on GATs.)
#### Types to borrow
| Field type | Borrowed type | Notes |
| ---------- | ------------- | ----- |
| strings | `&'a str` | |
| identifiers | `&'a IdentifierType` | |
| `Vec<_>` | `&'a [_]` | The inner type should not be borrowed. |
#### Types not to borrow
Inner types of `Vec`s _should not_ be borrowed, nor should `BTreeMap`s and such.
Structs also should not be borrowed, with the exception that if a struct:
- has fields that should be borrowed according to the table
above (strings, identifiers, `Vec`s), and
- is only used inside request blocks (i.e. not in response blocks or in
events),
then the struct should be lifetime-parameterized and apply the same rules to
their fields. So instead of
```rust
ruma_api! {
request: {
my_field: MyStruct,
}
// ...
}
pub struct MyStruct {
inner_string_field: String,
}
```
use
```rust
ruma_api! {
request: {
my_field: MyStruct<'a>
}
// ...
}
pub struct MyStruct<'a> {
inner_string_field: &'a str,
}
```
### Tracking Changes
If your changes affect the API of a user-facing crate (all except the `-macros` crates and