Folios are an ambiguous term.  This is partly deliberate, done with the full understanding that it makes things harder later, but easier now, and we have a harder job to do now.

As the documentation says, a folio is simply a new term for a non-tail page.  That is, it represents one or more pages of memory.  If it's more than one page, those pages were allocated with {{{__GFP_COMP}}} (i.e. are compound pages).

Folios give us a lot of type safety.  Referring to {{{page->mapping}}} or {{{page->index}}} is _dangerous_.  If you do that to a tail page, you'll get garbage.  Maybe you'll be lucky and see {{{TAIL_MAPPING}}} (not true for all tail pages), but there's no equivalent poison for {{{page->index}}}.  Similarly for {{{page->lru}}}, although if you do use it, you'll corrupt the compound page quickly enough that you'll probably notice.  You'll probably get away with using {{{page->private}}} for tail pages on 64-bit, but have problems on 32-bit.  etc.

But a lot of people want more type safety than that.  They don't want to be able to pass a slab page to {{{set_page_dirty()}}} (this would be a bad thing).  They don't want to be able to {{{lock_page()}}} a page table (_probably_ wouldn't hurt, but it's meaningless; you almost certainly meant to take the pte lock instead).  There's substantial disagreement about whether anon and file memory should be of different types.  I think that's a topic on which reasonable people can disagree, and we're going to have to keep disagreeing until we resolve it.

"More type safety" is how we come to the second meaning of folio, and that's not written down in the fine documentation.  Folios are _only_ for anon & file memory allocations.  We've already split out {{{struct slab}}} and {{{struct ptdesc}}}.  More types are to come (see MatthewWilcox/Memdescs for current thoughts).  This confuses people, including me.  It's nonsense to write {{{folio_test_slab()}}}, and yet we do because folios also have the "I am not a tail page" property and so we eliminate the "this might be a tail page, I have to look up the head page first" step.  Eventually with memdescs, we'll go back to calling {{{page_test_slab()}}} or something.