Kirby’s API style prefers simple nouns or verbs over verbose names. The upside is brevity, and often simplicity. The cost is — at least sometimes — the need to learn and remember what the short names don’t tell (cognitive load).
With longer and more explicit names, you might have found it easier to figure out that you needed to check (careful, this is not real Kirby code):
// This is ugly, but I know what it means
$site->getCurrentDisplayLanguageObject()->isDefaultLanguage();
While shorter names can be confusing:
// I could read this as "get a the general-purpose 'language' utility,
// and ask it what the 'default' language is (from the configuration)".
$site->language()->default();
Sometimes there might be balanced solutions:
// Okay I think I still get this one
$site->currentLanguage()->isDefault();
But good API design is hard and I’m not saying this last example is necessarily better that what Kirby used.
I looked into the functions, even default. Inside it it’s a loop to get each language. I don’t needed a loop, I just needed a function to know if the current language was the default one or not.
I also thought that default was returning the language code and not true or false.
3
Then I visited #site and language. I did not find anything about default language there.
Summery
I could combine those docs to figure out how to use it but I did not see that.
I also overlooked the default function as I thought it was returning the default language code.
Solutions
You have mention many of them already, I know…
More docs to cover everything.
Rename default to ìsDefault.
Way to see everything about language, without jumping around. Maybe have different tags, like “language” and “site”.
Some documentation tool, something like Grav API including references to or inline examples.