Phandles, specifier spaces, and cell names are simultaneously
extremely common and woefully underdocumented. Address that by:
- reworking our existing documentation on these subjects in
bindings-syntax.rst, fixing missing information in the
property syntax template as well
- adding a standalone guide which describes how all the pieces
fit together, providing a bridge for the gap between
DTS/bindings and C APIs
My goal is not to eventually make this a comprehensive place
where *all* specifier spaces are documented. It would be better (more
scalable, more discoverable) to improve the individual API pages to
cover the devicetree-related conventions that apply in each case.
That's a problem for someone else and another day, but we do need a
few concrete references in the DTS guides to keep the motivation
clear.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Generic improvements:
- clean up some language that needs adjusting
- rename some section headers and reorder some content to
improve readability
- add a table of contents to ease search
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
The bindings.rst page has gotten too big. Split it up into
sub-documents to improve readability and restore maintainability.
As part of this effort, move the /zephyr,user node documentation into
its own page in the guide. This page has proven extremely difficult
for users to spot in my experience, and it's meant as a convenience,
so let's make the documentation more convenient as well.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
