RE: documentation and code style

Håkon Alseth — Tue, 09 Aug 2016 08:04:11 GMT

Hi vbe,

Maybe there is obvious way how to find out what flags can user fill into:

uint8_t              service_type;
/**< Bit mask identifying services that the application intends to support for all peers. */

If it so please tell me - how to use your documentation to know what mask I can fill into service_type?

I agree with your conclusion. In the struct dm_application_param_t I cannot see any references to the bitmask that shall be populated in member .service_type. As you have already found; this shall not be of a type uint8_t, but of type service_type_t. Apart from this bug in the API (which I will report internally), the structure follows the SoftDevice API guidelines.

I agree that using enums instead of defines is easier to maneuver in, seen from the developers POV, but you do not have full control over your types, unless you type-cast at a later point, which may cause the flow to be a bit messy.

If it is truly imperfection in documentation - are you planning on filling gaps in documentation in near future? (- probably in most places adding adding \ref would be enough)

A \ref should have been added here, and type changed from uint8_t to service_type_t to align with generic API documentation.

Are you planning to use more enum instead of #define in your code? Or why would you prefer #define over enum? I'm really interested - perhaps you wanna have stronger control of type and enum can be sometimes encoded into uint32_t?

Stronger control of the types is the main reason. Enums can be 8/16/32 bits, depending on compiler, optimization, and settings used. Since our stack uses SVCalls in all API calls, it is important that the sizes match on "both ends of the SVCalls"

Thanks for reporting this back to us and helping us to improve our deliveries. It is always helpful to get feedback!

Cheers, Håkon