From 6b45931598fd8e405fd53f8fa35d72be639b73e1 Mon Sep 17 00:00:00 2001
From: Laurent Cheylus <foxy@free.fr>
Date: Fri, 27 Jun 2025 09:29:09 +0200
Subject: [PATCH] sync: improve documentation (#24799)

---
 vlib/sync/common_mutex.v   | 4 ++--
 vlib/sync/cond.v           | 6 +++---
 vlib/sync/once.v           | 5 +++--
 vlib/sync/sync_default.c.v | 6 +++---
 vlib/sync/waitgroup.c.v    | 8 +++++---
 5 files changed, 16 insertions(+), 13 deletions(-)

diff --git a/vlib/sync/common_mutex.v b/vlib/sync/common_mutex.v
index f2cf330ed7..ee08837cf8 100644
--- a/vlib/sync/common_mutex.v
+++ b/vlib/sync/common_mutex.v
@@ -1,11 +1,11 @@
 module sync
 
-// str returns a string representation of the Mutex pointer
+// str returns a string representation of the Mutex pointer.
 pub fn (m &Mutex) str() string {
 	return 'Mutex(${voidptr(m)})'
 }
 
-// str returns a string representation of the RwMutex pointer
+// str returns a string representation of the RwMutex pointer.
 pub fn (m &RwMutex) str() string {
 	return 'RwMutex(${voidptr(m)})'
 }
diff --git a/vlib/sync/cond.v b/vlib/sync/cond.v
index 807267d296..2fe6562761 100644
--- a/vlib/sync/cond.v
+++ b/vlib/sync/cond.v
@@ -20,7 +20,7 @@ pub fn new_cond(m &Mutex) &Cond {
 	}
 }
 
-// wait waits for condition notification
+// wait waits for condition notification.
 // NOTE: Spurious wakeups are possible; always use in a loop:
 // mutex.lock()
 // for !condition {
@@ -56,7 +56,7 @@ pub fn (mut c Cond) wait() {
 	c.mutex.lock()
 }
 
-// signal wakes one waiting thread
+// signal wakes one waiting thread.
 @[direct_array_access]
 pub fn (mut c Cond) signal() {
 	c.inner_mutex.lock()
@@ -71,7 +71,7 @@ pub fn (mut c Cond) signal() {
 	}
 }
 
-// broadcast wakes all waiting threads
+// broadcast wakes all waiting threads.
 @[direct_array_access]
 pub fn (mut c Cond) broadcast() {
 	c.inner_mutex.lock()
diff --git a/vlib/sync/once.v b/vlib/sync/once.v
index f03d8f3685..434931d539 100644
--- a/vlib/sync/once.v
+++ b/vlib/sync/once.v
@@ -16,7 +16,7 @@ pub fn new_once() &Once {
 	return once
 }
 
-// do executes the function `f()` only once
+// do executes the function `f()` only once.
 pub fn (mut o Once) do(f fn ()) {
 	if stdatomic.load_u64(&o.count) < 1 {
 		o.do_slow(f)
@@ -32,7 +32,7 @@ fn (mut o Once) do_slow(f fn ()) {
 	o.m.unlock()
 }
 
-// do_with_param executes `f(param)` only once`
+// do_with_param executes `f(param)` only once.
 // This method can be used as a workaround for passing closures to once.do/1 on Windows
 // (they are not implemented there yet) - just pass your data explicitly.
 // i.e. instead of:
@@ -49,6 +49,7 @@ fn (mut o Once) do_slow(f fn ()) {
 //    }, o)
 // ```
 
+// do_with_param executes the function `f()` with parameter `param` only once.
 pub fn (mut o Once) do_with_param(f fn (voidptr), param voidptr) {
 	if stdatomic.load_u64(&o.count) < 1 {
 		o.do_slow_with_param(f, param)
diff --git a/vlib/sync/sync_default.c.v b/vlib/sync/sync_default.c.v
index ddbc5de82a..1fab2f0623 100644
--- a/vlib/sync/sync_default.c.v
+++ b/vlib/sync/sync_default.c.v
@@ -215,7 +215,7 @@ pub fn (mut sem Semaphore) init(n u32) {
 // post increases/unlocks the counter of the semaphore by 1.
 // If the resulting counter value is > 0, and if there is another thread waiting
 // on the semaphore, the waiting thread will decrement the counter by 1
-// (locking the semaphore), and then will continue running. See also .wait() .
+// (locking the semaphore), and then will continue running. See also .wait().
 @[inline]
 pub fn (mut sem Semaphore) post() {
 	C.sem_post(&sem.sem)
@@ -225,7 +225,7 @@ pub fn (mut sem Semaphore) post() {
 // It it was not positive, it will waits for the semaphore count to reach a positive number.
 // When that happens, it will decrease the semaphore count (lock the semaphore), and will return.
 // In effect, it allows you to block threads, until the semaphore, is posted by another thread.
-// See also .post() .
+// See also .post().
 pub fn (mut sem Semaphore) wait() {
 	for {
 		if C.sem_wait(&sem.sem) == 0 {
@@ -246,7 +246,7 @@ pub fn (mut sem Semaphore) wait() {
 // try_wait tries to decrease the semaphore count by 1, if it was positive.
 // If it succeeds in that, it returns true, otherwise it returns false.
 // try_wait should return as fast as possible so error handling is only
-// done when debugging
+// done when debugging.
 pub fn (mut sem Semaphore) try_wait() bool {
 	$if !debug {
 		return C.sem_trywait(&sem.sem) == 0
diff --git a/vlib/sync/waitgroup.c.v b/vlib/sync/waitgroup.c.v
index 507789cf65..5bffb6384e 100644
--- a/vlib/sync/waitgroup.c.v
+++ b/vlib/sync/waitgroup.c.v
@@ -16,7 +16,7 @@ fn C.atomic_compare_exchange_weak_u32(voidptr, voidptr, u32) bool
 // Do not copy an instance of WaitGroup, use a ref instead.
 //
 // usage: in main thread:
-// `wg := sync.new_waitgroup()
+// `wg := sync.new_waitgroup()`
 // `wg.add(nr_jobs)` before starting jobs with `go ...`
 // `wg.wait()` to wait for all jobs to have finished
 //
@@ -32,12 +32,14 @@ mut:
 	sem        Semaphore // This blocks wait() until tast_countreleased by add()
 }
 
+// new_waitgroup creates a new WaitGroup.
 pub fn new_waitgroup() &WaitGroup {
 	mut wg := WaitGroup{}
 	wg.init()
 	return &wg
 }
 
+// init initializes a WaitGroup.
 pub fn (mut wg WaitGroup) init() {
 	wg.sem.init(0)
 }
@@ -67,12 +69,12 @@ pub fn (mut wg WaitGroup) add(delta int) {
 	}
 }
 
-// done is a convenience fn for add(-1)
+// done is a convenience fn for add(-1).
 pub fn (mut wg WaitGroup) done() {
 	wg.add(-1)
 }
 
-// wait blocks until all tasks are done (task count becomes zero)
+// wait blocks until all tasks are done (task count becomes zero).
 pub fn (mut wg WaitGroup) wait() {
 	nrjobs := int(C.atomic_load_u32(&wg.task_count))
 	if nrjobs == 0 {