docs: Ring Buffers docs are hidden away under unexpected title

[pfalcon]

We have the whole "Data Passing" chapter in docs: https://docs.zephyrproject.org/latest/kernel/data_passing/data_passing.html which includes: FIFO, LIFO, Stack, Message Queue, Mailbox, Pipe.

And suddenly, Ring Buffers are away from it, under "Other Services" https://docs.zephyrproject.org/latest/kernel/other/ring_buffers.html .

Ring Buffer is just another data data communication primitive in Zephyr. The fact that it's apparently destined to be "more low-level" than some other, should lead to it being hidden away from the general inventory of data-passing mechanisms in Zephyr.

[pfalcon]

@nashif : Following suggestion to not do multiple assignments, but IMHO you would be ack'ing this.

[pfalcon]

Not being able to see entire data passing hierarchy at once leads to d'oh moments like this: #9853 (comment)

[dbkinder]

So is the recommendation to move ring_buffers to the data_passing section, yes?

There's nothing "sudden" about this by the way, if you look at documentation in earlier releases (such as https://docs.zephyrproject.org/1.7.0/kernel/kernel.html ) you'll find ring buffers have been documented in "other services" for over two years.

[nashif]

ring buffers are not native kernel objects, we had a lengthy discussion about this in the past and there are very strong opinions about call them native kernel objects. That also the reason the are prefixed with sys_ instead of k_.

[dbkinder]

so what's the recommendation to close this issue? We could add a link to the ring buffers documentation in the kernel objects data passing documentation with your explanation that while they're data passing structures, they're not kernel objects.

[nashif]

recommendation is to leave this as is.

[pfalcon]

Thanks for comments.

So is the recommendation to move ring_buffers to the data_passing section, yes?

Yes.

There's nothing "sudden" about this

Yeah, I don't mean sudden in a sense of time. I thought that maybe they're not documented, or there's a glitch which caused that section to be excluded (IIRC we had such case lately). And then I suddenly found it under "Other Services". And I knew what I was looking for, maybe wouldn't find otherwise.

[pfalcon]

ring buffers are not native kernel objects, we had a lengthy discussion about this in the past and there are very strong opinions about call them native kernel objects.

I guess we're going into word-play here. If you look at the left of https://docs.zephyrproject.org/latest/kernel/data_passing/data_passing.html , you'll see:

Level 1 heading: Zephyr Kernel Primer
Level 2 heading: Data Passing
Level 3 headings: FIFOs, LIFOs, etc.
Level 2 heading: Other Services
Level 3 heading: Ring Buffers

So, word "native" is not involved in any way. Even word "object" isn't. Everything is under "Zephyr Kernel Primer", and the talk is about moving a level 3 section from one level 2 heading to another.

At the very least, we should do what @dbkinder suggests:

We could add a link to the ring buffers documentation in the kernel objects data passing documentation with your explanation that while they're data passing structures, they're not kernel objects.

But it's also a chance to think something like following: "If structure looks weird in the docs, them maybe the underlying structure also has issue, or at least distinctions there are less important to the external Zephyr API than it seems (all those native vs non-native, object vs non-object)."

Like, those may be important secondary facts (whose meaning should be explained in xrefed glossary), but the primary categorization is that all they are the data passing primitives.

[pfalcon]

we had a lengthy discussion about this in the past and there are very strong opinions about call them native kernel objects

Any references to that btw?

[pfalcon]

And it goes beyond that. "Polling" is again under "Other Services", while we have the "Synchronization" section. In which way polling is not synchronization but rather something "other" in the back where nobody sees it?

[nashif]

documentation for kernel and others has been restructured, open a new issue if you think this is not addressed.