Update/discuss design guidance

[sergey-shandar]

• .h and .c template with _az_cfg_preffix.h, _az_cfg_suffix.h and _az_cfg_warn.h.
• pure functions
• az_result structure, see [Design] AZ_RESULT and simple output values. #59
• in, in/out and out parameter conventions.
• callback template
  1. Core library

     typedef void * az_context;

  2. interface

     typedef my_result my_callback_f(az_context context, my_parameter a);
     
     typedef struct {
       az_context context;
       my_callback_f * f;
     } my_callback;
     
     #define MY_CALLBACK_CAST(CONTEXT, NAME) \
       AZ_STATIC_ASSERT(sizeof(CONTEXT) == sizeof(az_context));
       static my_callback NAME( \
         CONTEXT const context, \
         my_result (* const f)(CONTEXT, my_parameter)) { \
         return (my_callback){ .context = (az_context)context, .f = (my_callback_f)f }; \
       }

  3. implementation

     struct my_context { … };
     int my_callback_implementation(my_context * const context, my_parameter m);
     MY_CALLBACK_CAST(my_context *, az_my_callback_implementation_cast);

• a discriminated union for integers is an integer, examples az_result, char + EOF.
• EOF convention
• polymorphic iterator
• reactive parsers
• private fields

[gilbertw]

Guidelines are up to date.
https://azure.github.io/azure-sdk/general_introduction.html