From 9e6575eaab5e471019ff3af9f0a633182c1d6f4d Mon Sep 17 00:00:00 2001
From: Larpon <Larpon@users.noreply.github.com>
Date: Sun, 27 Dec 2020 19:14:43 +0100
Subject: [PATCH] runtime: document all functions (#7612)

---
 vlib/runtime/runtime.c.v         | 13 +++++++++++++
 vlib/runtime/runtime.v           | 16 ++++++++--------
 vlib/runtime/runtime_nix.c.v     |  3 ++-
 vlib/runtime/runtime_windows.c.v |  1 +
 4 files changed, 24 insertions(+), 9 deletions(-)
 create mode 100644 vlib/runtime/runtime.c.v

diff --git a/vlib/runtime/runtime.c.v b/vlib/runtime/runtime.c.v
new file mode 100644
index 0000000000..e2df8e3d72
--- /dev/null
+++ b/vlib/runtime/runtime.c.v
@@ -0,0 +1,13 @@
+// Copyright (c) 2019-2020 Alexander Medvednikov. All rights reserved.
+// Use of this source code is governed by an MIT license
+// that can be found in the LICENSE file.
+
+module runtime
+
+//$if linux {
+fn C.sysconf(name int) i64
+//}
+
+//$if windows {
+fn C.GetCurrentProcessorNumber() u32
+//}
diff --git a/vlib/runtime/runtime.v b/vlib/runtime/runtime.v
index bf56a9651e..24562e9023 100644
--- a/vlib/runtime/runtime.v
+++ b/vlib/runtime/runtime.v
@@ -6,14 +6,10 @@ module runtime
 
 import os
 
-//$if linux {
-fn C.sysconf(name int) i64
-//}
-
-//$if windows {
-fn C.GetCurrentProcessorNumber() u32
-//}
-
+// nr_jobs returns the same as `nr_cpus` with the difference that if an
+// environment variable `VJOBS` is set, and has a value > 0,
+// then `nr_jobs` will return that number instead.
+// This is useful for runtime tweaking of e.g. threaded or concurrent code.
 pub fn nr_jobs() int {
 	mut cpus := nr_cpus()
 	// allow for overrides, for example using `VJOBS=32 ./v test .`
@@ -24,21 +20,25 @@ pub fn nr_jobs() int {
 	return cpus
 }
 
+// is_32bit returns true if the current executable is running on a 32 bit system.
 pub fn is_32bit() bool {
 	$if x32 { return true }
 	return false
 }
 
+// is_64bit returns true if the current executable is running on a 64 bit system.
 pub fn is_64bit() bool {
 	$if x64 { return true }
 	return false
 }
 
+// is_little_endian returns true if the current executable is running on a little-endian system.
 pub fn is_little_endian() bool {
 	$if little_endian { return true }
 	return false
 }
 
+// is_big_endian returns true if the current executable is running on a big-endian system.
 pub fn is_big_endian() bool {
 	$if big_endian { return true }
 	return false
diff --git a/vlib/runtime/runtime_nix.c.v b/vlib/runtime/runtime_nix.c.v
index bccd7497d2..2fe51d713d 100644
--- a/vlib/runtime/runtime_nix.c.v
+++ b/vlib/runtime/runtime_nix.c.v
@@ -1,5 +1,6 @@
 module runtime
 
+// nr_cpus returns the number of virtual CPU cores found on the system.
 pub fn nr_cpus() int {
 	$if linux {
 		return int(C.sysconf(C._SC_NPROCESSORS_ONLN))
@@ -11,4 +12,4 @@ pub fn nr_cpus() int {
 		return int(C.sysconf(C._SC_NPROCESSORS_ONLN))
 	}
 	return 1
-}
\ No newline at end of file
+}
diff --git a/vlib/runtime/runtime_windows.c.v b/vlib/runtime/runtime_windows.c.v
index 6a345644bf..52098201eb 100644
--- a/vlib/runtime/runtime_windows.c.v
+++ b/vlib/runtime/runtime_windows.c.v
@@ -8,6 +8,7 @@ struct C.SYSTEM_INFO {
 }
 fn C.GetSystemInfo(&C.SYSTEM_INFO)
 
+// nr_cpus returns the number of virtual CPU cores found on the system.
 pub fn nr_cpus() int {
 	sinfo := C.SYSTEM_INFO{}
 	C.GetSystemInfo(&sinfo)