Multi keyring child keyrings vs children keyrings

[seebees]

Should the interface be changed to child to simplify the documentation grammar?

[robin-aws]

+1. The inconsistency seems to fall out naturally from implementations using just "children" with the fact that they are also keyrings implied or spelled out in the type of references instead. I assert either "children" or "child keyring" is fine.

AFAICT a search-and-replace in the specification and the Java implementation (https://github.com/aws/aws-encryption-sdk-java/blob/keyring/src/main/java/com/amazonaws/encryptionsdk/keyrings/MultiKeyring.java#L37) should be all that's necessary.

[mattsb42-aws]

@robin-aws IIRC the original objection was that using the term "children keyrings" force us to talk in docs about "a children keyring", which does not make grammatical sense.

[robin-aws]

Agreed, and I assert "children keyrings" doesn't make sense because it uses "children" like an adjective, implying it's a type of keyring. I was trying to say that JUST "children" by itself (making it a noun) or "child keyring" is valid, and that actual implementation code should be able to use the former for field names etc.

This does touch on the consistent naming topic we should call out explicitly: if the spec uses "Foo" to label a concept or thing, what derivations of "Foo" are implementations allowed to use in order to be idiomatic? How do we ensure that users can still find "Foo" in the implementations if the exact terms are different? Is it enough just to link from spec features to implementation files?

[mattsb42-aws]

I was trying to say that JUST "children" by itself (making it a noun) or "child keyring" is valid, and that actual implementation code should be able to use the former for field names etc.

In the plural form, ok, it's workable though I'm not convinced that it is correct English because both the modifier "children" and the object "keyrings" are plural. The real problem, though, comes when you look for the singular form.

• child keyrings -> child keyring : This is clear and follows common English language rules.
• children keyrings -> children keyring : This makes it sound like you are describing a single instance of a specific kind of keyring that is characterized by the modifier "children". This is not congruent with the intent of the modifier as a description of the relationship between the list of keyrings and the multi-keyring.
• children keyrings -> child keyring : This changes both the modifier and the object at the same time, making me confused what each refers to or if they even describe the same thing.

[mattsb42-aws]

JUST "children" by itself (making it a noun) or "child keyring" is valid

...I misread that the first time around. Agreed. Leaving my brain-dump above though, for context.