Add support for source forwarding in Error derive

[MegaBluejay]

Resolves #428
Related to #110, #200

Synopsis

Adds support for #[error(forward)] attribute, which forwards the .source() implementation to a field.

Solution

Use existing forward fields in State for parsing the attributes, and keep the source-inferring logic the same as without forwarding.

Backtrace forwarding

The current behaviour is that if the field annotated/inferred to be the source is annotated with #[error(backtrace)], a forwarded provide() is generated.

This was in the example usage, but not documented in the list above, so I added it.

Checklist

• Documentation is updated (if required)
  • Document new behaviour
  • Add an explanation of advised usage as previously suggested?
• Add errors on usage of #[error(forward)] when no source field was specified/inferred
• Tests are added/updated (if required)
• CHANGELOG entry is added (if required)

[MegaBluejay]

@tyranron I implemented this with the existing parsing since it was an easy change.

Would it be preferable to refactor the derive first, similarly to #286?

[tyranron]

@MegaBluejay no, let's postpone refactoring here as a minor priority task.

[JelteF]

copy paste error?

Suggested change

	4. The source field is annotated with `#[error(backtrace)]`. Then it would
	4. The source field is annotated with `#[error(forward)]`. Then it would

[MegaBluejay]

No that's correct, provide is forwarded only when the source is annotated with #[error(backtrace)].

That behaviour is unchanged in this PR.

The reasoning for keeping a separate attribute is to make source forwarding work on stable, since there's no good way of generating feature-gated code.

I also think this is somewhat unintuitive, but I haven't come up with a better idea.

Perhaps it could make sense to disallow #[error(backtrace)] on the source field if there's no #[error(forward)]?

[JelteF]

I'm having a hard time understanding the usecase for such forwarding. Could you share a concrete example for when this is useful?

[MegaBluejay]

Could you share a concrete example for when this is useful?

The main use case I can see is transparent error variants

Something like

#[derive(Debug, Display, Error)
enum Error {
    ...
    #[error(forward)]
    #[display("{_0}")]
    #[debug("{_0:?}")]
    Other(anyhow::Error),
}

Where there's no new information added by the wrapper, so adding it to the source stack is unnecessary.

[tyranron]

@MegaBluejay yes, I start thinking that maybe transparent is better here than forward. Let's postpone it for a little while... I'll write up some design thoughts during the following week. And, of course, will describe the motivation more clearly.