Improve RecentEra docs

[Anviking]

Related Advice Process Decision: https://docs.google.com/document/d/1xazQNECWex3GWp2-yzAeJGnYvAHchamgNVvFDs3ydcg/edit?tab=t.0#heading=h.gjdgxs

[abailly]

Is this still relevant?

[Anviking]

IMO RecentEra would still deserve some improved docs.

@HeinrichApfelmus do you think we could agree on some variation of this without too much difficulty?

This example in particular is currently in conflict with the decision

myCardanoApiTx :: IsRecentEra era -> RecentEra -> CardanoApi.Tx (CardanoApiEra era)

had concerns about it, don't remember if resolved, but can ignore for now, could copy the examples from the decision doc exactly as a first step.

[HeinrichApfelmus]

Suggested change

	-- renderCliTx :: IsRecentEra era -> Tx era -> Text
	-- myCardanoApiTx :: IsRecentEra era -> RecentEra -> CardanoApi.Tx (CardanoApiEra era)
	-- renderCliTx :: IsRecentEra era => Tx era -> Text
	-- myCardanoApiTx :: IsRecentEra era => RecentEra era → CardanoApi.Tx (CardanoApiEra era)

The other variants do not type check, I believe.

[HeinrichApfelmus]

This example in particular is currently in conflict with the decision

myCardanoApiTx :: IsRecentEra era -> RecentEra -> CardanoApi.Tx (CardanoApiEra era)

had concerns about it, don't remember if resolved,

I think the specific trouble with myCardanoApiTx might have been that CardanoApiEra is not an injective type family, and specifying the return type is not enough to determine era — this type would be ambiguous.

In general, however, the decision document does imply that era in the return value is sufficient cause to not have have it as an explicit argument. For example,

parseThisRecentEra :: IsRecent era => ByteString → Maybe (RecentEra era)

is preferred over

parseThisRecentEra' :: IsRecent era => RecentEra era → ByteString → Maybe (RecentEra era)

but can ignore for now, could copy the examples from the decision doc exactly as a first step.

Yes, please. Copying the examples from the decision document exactly is a good idea.