From bfd0bd1fb41f0e65b99304995cf16619e8e4ba4a Mon Sep 17 00:00:00 2001
From: Larpon <Larpon@users.noreply.github.com>
Date: Sun, 7 Feb 2021 11:42:24 +0100
Subject: [PATCH] builtin: doc chan.v channel stub (#8577)

---
 vlib/builtin/chan.v | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)
 mode change 100755 => 100644 vlib/builtin/chan.v

diff --git a/vlib/builtin/chan.v b/vlib/builtin/chan.v
old mode 100755
new mode 100644
index 8ee7c56d03..0185fdb5d7
--- a/vlib/builtin/chan.v
+++ b/vlib/builtin/chan.v
@@ -1,20 +1,32 @@
 module builtin
 
+// ChanState describes the result of an attempted channel transaction.
 enum ChanState {
 	success
 	not_ready // push()/pop() would have to wait, but no_block was requested
 	closed
 }
 
-// The following methods are only stubs. The real implementation
-// is in `vlib/sync/channels.v`
+/*
+The following methods are only stubs.
+The real implementation is in `vlib/sync/channels.v`
+*/
 
+// close closes the channel for further push transactions.
+// closed channels cannot be pushed to, however they can be popped
+// from as long as there is still objects available in the channel buffer.
 pub fn (ch chan) close() {}
 
+// try_pop returns `ChanState.success` if an object is popped from the channel.
+// try_pop effectively pops from the channel without waiting for objects to become available.
+// Both the test and pop transaction is done atomically.
 pub fn (ch chan) try_pop(obj voidptr) ChanState {
 	return .success
 }
 
+// try_push returns `ChanState.success` if the object is pushed to the channel.
+// try_push effectively both push and test if the transaction `ch <- a` succeeded.
+// Both the test and push transaction is done atomically.
 pub fn (ch chan) try_push(obj voidptr) ChanState {
 	return .success
 }