search

Azure / azure-sdk-for-c

This repository is for active development of the Azure SDK for Embedded C. For consumers of the SDK we recommend visiting our versioned developer docs at https://azure.github.io/azure-sdk-for-c.
MIT License
226 stars 120 forks source link

Document more explicitly to not use _internal only fields with in-source comments #1918

Closed ahsonkhan closed 8 months ago

ahsonkhan commented 3 years ago

Upstream dependencies shouldn't be relying on or referencing fields that are marked _internal. Similarly, types and methods prefixed with _az are private implementation (that aren't documented) and shouldn't be used.

For example, add a comment for each nested _internal struct within the repo: https://github.com/Azure/azure-sdk-for-c/blob/52b7d3c4a005924739b420d2acffe275f0a6c9a5/sdk/inc/azure/core/az_json.h#L306-L318

Example comment:

// These are internal only fields and are subject to change without notice. They are not meant to be used by anyone externally.

Related context: https://github.com/azure-rtos/netxduo/issues/47#issuecomment-915642478

This is similar to the note we have above each header file: https://github.com/Azure/azure-sdk-for-c/blob/84bfe57b50091d88dc993ce80e95ca435aaa0d16/sdk/inc/azure/az_iot.h#L9-L12

cc @JeffreyRichter, @RickWinter

rmknan commented 1 year ago

Hello, I would like to work on this. I need to add these comments only in the header file mentioned?

ahsonkhan commented 1 year ago

That's great, thanks @rmknan.

Please search for all header files that have nested _internal structs and add the comment above them, not just the ones mentioned in the issue. You can try searching in your IDE of choice to catch the various instances within the .h files (such as Ctrl+Shift+F in VSCode).

// These are internal only fields and are subject to change without notice. They are not meant to be used by anyone externally.

For example, the recommended comment should be added on top of this too: https://github.com/Azure/azure-sdk-for-c/blob/59b721bb33a6a0653824e5c52f1458016a515044/sdk/inc/azure/core/internal/az_http_internal.h#L38-L41

Same here/elsewhere: https://github.com/Azure/azure-sdk-for-c/blob/59b721bb33a6a0653824e5c52f1458016a515044/sdk/inc/azure/core/az_context.h#L38-L44

rmknan commented 1 year ago

PR #2622

github-actions[bot] commented 8 months ago

Hi @ahsonkhan, we deeply appreciate your input into this project. Regrettably, this issue has remained inactive for over 2 years, leading us to the decision to close it. We've implemented this policy to maintain the relevance of our issue queue and facilitate easier navigation for new contributors. If you still believe this topic requires attention, please feel free to create a new issue, referencing this one. Thank you for your understanding and ongoing support.