Unclear path substition rules

[drahnr]

It is not clear how to specify the substitute syn::Paths required as argument.

A few things remain puzzling:

1. what is the relative base module needed to get a substitution match?
2. does it have to be absolute paths?
3. do bare types (so i.e. just an Ident) themselves suffice for matching?

let path = &ty.ty.path;
            // Don't generate a type if it was substituted - the target type might
            // not be in the type registry + our resolution already performs the substitution.
            if self.settings.substitutes.contains(dbg!(&path.segments)) {
                continue;
            }

is the relevant line, but it's not clear what path.segments contains and relative to what base.

[drahnr]

warning: typepath is: ["gensyn_runtime_primitives", "indices", "CommitteeIndex"]
warning: typepath is: ["gensyn_runtime_primitives", "availability", "AvailabilityItemDescriptor"]
warning: typepath is: ["gensyn_runtime_primitives", "ErasureRoot"]
...

so bottom line is only path segments are compared for matching.

On the other hand side, the replacement must be an absolute path.

It'd be great to get this documented.

[jsdw]

Sorry for the slow response! I think the solution to this would be to extend the docs here a little:

https://docs.rs/subxt/0.34.0/subxt/attr.subxt.html#substitute_typepath---with--

Here we could note that the replacement path must be absolute (IIRC this is so that it is unambiguous, because the macro doesn't know in which path it's being called, but I'd have to check). It does already mention that it substitutes based on paths I think with "replaces any reference to the generated type at the path given by path with a reference to the path given by with" but perhaps we could make this clearer?

I think it'd be nice to also add here an example of how one can avoid using this attribute in some cases (the usual pattern here is to create a custom type and then impl From<runtime::GeneratedType> for MyType etc for easy conversion to/from your type from the generated one). It's always better to avoid where possible, since replacing generated types with custom types can easily go wrong (eg if the custom type is a different share to encoding/decoding fails, or if the custom type doesn't implement the traits that are required of it from other codegenned types).

Do you have any other thoughts on what we could clarify/tweak @drahnr?