Expand Foldable docs: add sections for collectFirst, findM, foldMapA/M/K, minimumByList, partitionEither

[arnavsharma990]

Motivation

The Foldable docs page (docs/typeclasses/foldable.md) was only 138 lines and covered only the most basic methods despite Foldable having grown a rich API over several releases. Many commonly-used methods had zero documentation outside their Scaladoc.

Changes

Adds 7 new sections with prose explanations and runnable mdoc examples:

• collectFirst / collectFirstSome — short-circuiting search via PartialFunction or A => Option[B]
• collectFold / collectFoldSome — filtered fold accumulating into a Monoid
• findM — monadic short-circuiting find with an effectful predicate
• foldMapM / foldMapA — fold-map in a Monad / Applicative context, with a note on the short-circuiting difference
• foldMapK — fold-map via MonoidK
• minimumByList / maximumByList — collect all tied minimum/maximum elements
• partitionEither — split a structure into two collections via Either

[Copilot]

Pull request overview

This pull request expands the Foldable typeclass documentation by adding comprehensive coverage of 7 commonly-used but previously undocumented methods. The additions follow the established mdoc documentation pattern, providing clear prose explanations followed by executable code examples.

Changes:

• Added documentation sections for collectFirst/collectFirstSome, collectFold/collectFoldSome, findM, foldMapM/foldMapA, foldMapK, minimumByList/maximumByList, and partitionEither
• Each section includes practical examples demonstrating the methods' behavior and use cases
• All examples are formatted as mdoc code blocks that will be validated during documentation build

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The statement "it cannot short-circuit" is too strong. While foldMapA does not guarantee short-circuiting behavior (unlike foldMapM which guarantees it via the Monad constraint), some Applicative instances like Option do actually short-circuit. The current wording could mislead readers into thinking foldMapA will never short-circuit.

Consider rewording to something like: "foldMapA is the Applicative variant — it does not guarantee short-circuiting (though some Applicative instances like Option do), but works in a broader set of contexts."

Alternatively, since the example at line 208 already mentions "foldMapA behaves the same for Option", you could simply say "foldMapA is the Applicative variant — it works in a broader set of contexts but may not short-circuit for all Applicative instances."

Suggested change

	in `Option`). `foldMapA` is the `Applicative` variant — it cannot short-circuit but
	works in a broader set of contexts.
	in `Option`). `foldMapA` is the `Applicative` variant — it works in a broader set of
	contexts but may not short-circuit for all `Applicative` instances.