docs: update k_pipe documentation to align with the rewritten interface

This commit updates the k_pipe documentation to reflect the rewritten
interface.
Changes include:

* Detailed explanations of k_pipe concepts, initialization, and usage.
* Examples for defining, writing to, reading from, flushing,
	and closing a pipe.
* Clarified behavior in edge cases and introduced enhanced error-handling
  details.

Updated suggested use cases and API references.

Signed-off-by: Måns Ansgariusson <Mansgariusson@gmail.com>