[ docs ] Improved documentation for Prelude.Interfaces

[user470750]

Description

• Add documentation for the Applicative interface and the pure, <*>, *>, and <* functions, including code examples. Examples use == in accordance with the documentation style in Prelude.Interfaces.
• Add documentation for mapHom function following the style of the documentation for bimap, mapFst, mapSnd documentation.
• Add documentation for Traversable and Bitraversable intefaces.
• Add documentation for named interfaces implementations.
• Add documentation for Bifoldable interface following the style of the documentation for Foldable.

Self-check

• I confirm that this contribution did not involve GenerativeAI nor Large Language Models.

[joelberkeley]

IMO the @ fs are unnecessary here, and busy the docs. They're also not reflected by docs for a and b later

[user470750]

I based my choice of which arguments to document on the existing documentation for Functor.

[joelberkeley]

ah, well I guess I disagree with Edwin there. But yeah it makes sense to copy Functor's style.

[joelberkeley]

Note this example doesn't convey that the second effect is used. The converse of the (*>) example might help

Main> Just 2 <* Nothing
Nothing

It's a shame sth like State wouldn't be suitable here.

[user470750]

Thank you for pointing this out, I'll add such an example.

[user470750]

Added the second example for <*.

[joelberkeley]

Is "structure" always appropriate? What about IO or State? You use Applicative further down, though I don't think that's strictly true either. Is the Applicative not the pure and (<*>), rather than e.g. the Maybe? I'm unsure if Maybe "is an applicative functor" (small "a").

I'm aware that genericity of these interfaces will make it difficult to document them accurately, without it becoming impractically abstract.

[user470750]

For example, the word "structure" is used in the tutorial for Functor:

Idris2/docs/source/tutorial/interfaces.rst

Lines 238 to 239 in 811e065

	A functor allows a function to be applied across a structure, for
	example to apply a function to every element in a ``List``:

As for the wording "Applicative", I'm using it by analogy with the documentation for Biapplicative though I'm not sure how reliable a source the tests are for documentation wording.
It might make sense to use the same wording ("Applicative") for pure as well, for consistency.
In some of the phrasing, I also looked at Haskell for reference (e.g. "functor with application").
Also for example, the documentation for the functions related to Functor (map, <$>, <&>, etc.) uses the wording "a parameterised type".

Do you have any suggestions for alternative wording instead of "structure" and "Applicative"?

[joelberkeley]

I would guess the haskell docs would be the standard to follow. And they call it a structure, so seems sensible.