Update `#[extendr]` usage documentation with breaking changes.

[jtlandis]

With the PR extendr/extendr#882, We should consider updating the documentation reflecting that in order for extendr functions to take custom rust structs as arguments, or return custom rustt structs, then they need to implement T: TryFrom<Robj> and Robj: From<T> respectively. which can be be donee now with annotating #[extendr] on those rust objects directly.

Also if the user wants to implement their own method, then they shouldn't use the #[extendr] macro on their structs.

[JosiahParry]

Specifically they need to be external pointers I believe

[jtlandis]

@JosiahParry I think that depends on the users rust struct.

I believe there are two flavors of extendr Rust objects, objects that are a thin wrapper over R objects, and those that aren't.

For example, I believe the following would be valid in extendr

use extendr_api::prelude::*;

pub struct GRanges {
  robj: Robj,
}

impl TryFrom<Robj> for GRanges {
  fn try_from(value: Robj) -> Result<GRanges> {
    // should probably have more checks here
    if value.inherits("GRanges") {
      Ok(GRanges{ robj: value })
    } else {
      Err(Error::Other(String::from("Not a GRanges Object")))
  }
}

impl From<GRanges> for Robj {
  fn from(value: GRanges) -> Robj {
    value.robj.clone()
  }
}

In the above, it would be fairly redundant for the rust GRanges to be an external pointer that points back to R.

However, if the Rust object is more than just this thin wrapper, then it would be good practice for them to use an external pointer.

[JosiahParry]

@jtlandis I'm thinking something more along the lines of this: https://github.com/JosiahParry/geoarrowrs/blob/main/src/rust/src/ffi/mod.rs

I have implemented most of the varieties of TryFrom for Robj and vice-versa here. The class name isn't the struct name—so I think that alone would make these things incompatible.

Then there's also the idea presented at https://extendr.github.io/user-guide/serde-integration.html#using-tryfrom where you have a struct e.g. MPoint(Vec<Point>) which is represented in R as a data.frame and the class name is irrelevant.

It isn't immediately clear how custom implementations of TryFrom / From etc, would play together. I think the general stance should probably be along the lines of

"if you're using #[extendr] on impls blocks, then you probably should also use it on the struct too and not roll your own"

[jtlandis]

Users should definitely not make their own implementations of TryFrom / From if also using #[extendr] on impl blocks. If they did, then they would have to connect their objects to the environments made by extendr wrappers.