C++ Client Library Public Header Structure #8348
Conversation
antkmsft
requested review from
JeffreyRichter,
LarryOsterman and
RickWinter
as code owners
| fantasticgizmos/ | ||
| fantasticgizmos_models.hpp <-- all models for the Gizmos service. | ||
| amazing_gadget_client.hpp | ||
| amazing_gadget_client_options.hpp <-- all options for the Amazing Gadget client, both Client Options and operation (method) options. |
There was a problem hiding this comment.
| amazing_gadget_client_options.hpp <-- all options for the Amazing Gadget client, both Client Options and operation (method) options. | |
| amazing_gadget_client_options.hpp <-- all options for the Amazing Gadget client, both client options and operation (method) options. |
| @@ -697,6 +697,27 @@ struct HashComputation { | |||
| } // unnamed namespace | |||
| {% endhighlight %} | |||
|
|
|||
| #### Client Library Public Header Structure | |||
|
|
|||
| Example: Azure Fantastic Gizmos service has two clients, AmazingGadgetClient and AwesomeWidgetClient. | |||
There was a problem hiding this comment.
I think this example is great in illustrating/clarifying the expected physical structure of C++ header files on disk.
That said, we should add a "MUST/DO" guideline with an id above the example to highlight this is what we expect:
| Example: Azure Fantastic Gizmos service has two clients, AmazingGadgetClient and AwesomeWidgetClient. | |
| {% include requirement/MUST id="cpp-design-physical-public-headers" %} structure the public header files using separate client specific filenames for clients, options, LROs, and pagers, and service specific filename for models. | |
| Example: Azure Fantastic Gizmos service has two clients, AmazingGadgetClient and AwesomeWidgetClient. |
| awesome_widget_client_paged_responses.hpp | ||
| dll_import_export.hpp <-- AZURE_GIZMOS_DLLEXPORT macro definition. | ||
| rtti.hpp <-- AZURE_GIZMOS_RTTI macro definition. | ||
| ``` |
There was a problem hiding this comment.
Consider adding a note after to highlight the importance of this in C++, since header file names/locations are part of the public contract in a source distributed language like C++, which doesn't show up in other languages.
| ``` | |
| ``` | |
| **Note:** The names and location of public header files are part of the public API surface in C++ and have to be stable to avoid breaking end customers who `#include` them directly in their applications. |
|
We could consider using the opportunity to update tables SDK public headers to align with this guideline before we GA (since we can't change them post-GA without it being a breaking change): Rename:
There are no LROs in Tables as far as I can tell, so no change needed around that. For existing GA'd services, we'd leave them as-is. cc @gearama |
|
FYI @ronniegeraghty as the C++ PM :) |
No description provided.