Clarify Z_ APIs naming conventions and intended scope

[fabiobaltieri]

Hi, I was trying understand the intended scope and recommended usage of Z_ prefixed macros in Zephyr, specifically Z_STRUCT_SECTION_ITERABLE, but I haven't been able to find explicit documentation about it.

My understanding from the usage in the device model code, and the commit that excludes them from the external documentation (fb4d9c0) is that Z_ symbols are considered internal. Does this mean that they should not be used outside of the core code base?

The iterable macros would be useful at application level, so I'm wondering if we should add a non internal wrapper and documentation for those (or just use them as is).

For context, the only documentation I found about naming is an old page in the wiki (https://github.com/zephyrproject-rtos/zephyr/wiki/Naming-Conventions).

Tagging @nashif (from the patch and wiki) and @KAGA164 (implemented nfc support in NCS using these), who may know more about this.

Thanks!

[carlescufi]

@fabiobaltieri we have #29569 to track this, although unfortunately we haven't had much time lately to discuss this due to other priorities. Maybe you could close this one and add a comment there?

[fabiobaltieri]

Thanks @carlescufi, yes I'll close this and track the issue you mentioned, which answers my initial question. I may open a separate PR to propose publishing the iterables APIs but that's a different topic altogether.