Document that buildArity() must take a sorted list of features

[kennytm]

Arity::lookupFeature (thus Record::lookupFeature) uses binary search to find a feature. This requires the features to be totally ordered. But buildArity() won't check if the features are sorted. This causes strange "illegal field selection" errors when developers are unaware of such caveat.

I don't think it's possible for buildArity() to sort the features, because it needs to be matched with buildRecord(). But we could at least add some warning in the doc? Or maybe add an is_sorted() check in debug mode.

[sjrd]

Ah indeed, buildArity() was designed to receive the features in the correct order. It should certainly at least be documented. Maybe a check in debug mode would be a good idea, too.