I'd argue that for public APIs (defined as API users don't site next to/are the same as the API devs) this concern with "getting out of date" is moot compared t

I'd argue that for public APIs (defined as API users don't site next to/are the same as the API devs) this concern with "getting out of date" is moot compared to the benefit of detailed docs. If anything, it's the API signatures that get out of sync with the user's needs. And as anyone who's ever tried to deprecate public APIs will know, it's a real pain, frustrating to users and devs alike.