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

[ahsonkhan]

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]

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

[ahsonkhan]

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]

PR #2622

[github-actions[bot]]

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.