Jon, > I don't know about user friendly; I can wade through the technical details. > > I think one thing that is annoying about the API is a lack of consistency. > Here are some examples: > > - Sometimes the flag is "u8 is_ipv4", other times it is "u8 is_ipv6". > - Sometimes the flag is "u8 is_ip4", other times it is "u8 is_ip6".
Annoying indeed. For these one suggestion has been to remove them and instead use address/prefix types that have address-family included. > - Sometimes the flag is "u8 is_add", or "u8 is_del", or "u32 is_add". if we want something like a CRUD API, it might be better to have separate _delete messages. Often they don't have same parameters like the _add. Opinions? > - "is_enable" vs "is_enabled" > - Some API calls are "foo_add_del", some are "foo_add_replace", > and some are "foo_add" and "foo_del" Yep. Good if we could agree on one convention here. > I know that sounds trivial. I get that. But it makes for tough anticipation > and violates some principle of least-surprise-or-another. Agree. I think this inconsistency just adds confusion and irritation too. > > I get that different people work on different areas, but there needs to > be some consistency both in the names of the API calls and within > the API fields themselves. > > It would be documentationally nice for the API comment blocks to > explicitly denote what default values pertain to the fields of an API call. > Similarly, denote what the values of the "invalid" entry are. Is it 0? > Or is it -1 or is it ~0? Yes, I have also seen people want to add enums and perhaps do constants for these. Cheers, Ole
signature.asc
Description: Message signed with OpenPGP
_______________________________________________ vpp-dev mailing list vpp-dev@lists.fd.io https://lists.fd.io/mailman/listinfo/vpp-dev
