TheCloud/v
1
0
Fork 0
mirror of https://github.com/vlang/v.git synced 2025-09-09 15:27:05 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: cleanup doc comments of public APIs in benchmark, bitfield, and build

Browse Source
This commit is contained in:
Delyan Angelov 2025-07-02 16:54:10 +03:00
parent b305fa5743
commit 74b6e3b5c7
3 changed files with 34 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
vlib/benchmark/benchmark.v
View File

@ -129,7 +129,7 @@ pub fn start() Benchmark {
return b return b
} }
// measure prints the current time spent doing `label`, since the benchmark was started, or since its last call // measure prints the current time spent doing `label`, since the benchmark was started, or since its last call.
pub fn (mut b Benchmark) measure(label string) i64 { pub fn (mut b Benchmark) measure(label string) i64 {
b.ok() b.ok()
res := b.step_timer.elapsed().microseconds() res := b.step_timer.elapsed().microseconds()
@ -138,8 +138,7 @@ pub fn (mut b Benchmark) measure(label string) i64 {
return res return res
} }
// record_measure stores the current time doing `label`, since the benchmark // record_measure stores the current time doing `label`, since the benchmark was started, or since the last call to `b.record_measure`.
// was started, or since the last call to `b.record_measure`.
// It is similar to `b.measure`, but unlike it, will not print the measurement // It is similar to `b.measure`, but unlike it, will not print the measurement
// immediately, just record it for later. You can call `b.all_recorded_measures` // immediately, just record it for later. You can call `b.all_recorded_measures`
// to retrieve all measures stored by `b.record_measure` calls. // to retrieve all measures stored by `b.record_measure` calls.
@ -256,8 +255,7 @@ pub fn (b &Benchmark) total_message(msg string) string {
return tmsg return tmsg
} }
// all_recorded_measures returns a string, that contains all the recorded // all_recorded_measures returns a string, that contains all the recorded measure messages, done by individual calls to `b.record_measure`.
// measure messages, done by individual calls to `b.record_measure`.
pub fn (b &Benchmark) all_recorded_measures() string { pub fn (b &Benchmark) all_recorded_measures() string {
return b.measured_steps.join_lines() return b.measured_steps.join_lines()
} }

72
vlib/bitfield/bitfield.v
View File

@ -57,8 +57,8 @@ pub fn from_bytes(input []u8) BitField {
return output return output
} }
// from_bytes_lowest_bits_first converts a byte array into a bitfield // from_bytes_lowest_bits_first converts a byte array into a bitfield.
// [0x0F, 0x01] => 1111 0000 1000 0000 // For example: [0x0F, 0x01] => 1111 0000 1000 0000
pub fn from_bytes_lowest_bits_first(input []u8) BitField { pub fn from_bytes_lowest_bits_first(input []u8) BitField {
mut output := new(input.len * 8) mut output := new(input.len * 8)
for i, b in input { for i, b in input {
@ -67,8 +67,8 @@ pub fn from_bytes_lowest_bits_first(input []u8) BitField {
return output return output
} }
// from_str converts a string of characters ('0' and '1') to a bit // from_str converts a string of characters ('0' and '1') to a bitfield.
// array. Any character different from '0' is treated as '1'. // Any character different from '0' is treated as '1'.
pub fn from_str(input string) BitField { pub fn from_str(input string) BitField {
mut output := new(input.len) mut output := new(input.len)
for i in 0 .. input.len { for i in 0 .. input.len {
@ -79,8 +79,7 @@ pub fn from_str(input string) BitField {
return output return output
} }
// str converts the bit array to a string of characters ('0' and '1') and // str converts the bit array to a string of characters ('0' and '1').
// return the string
pub fn (input BitField) str() string { pub fn (input BitField) str() string {
mut output := '' mut output := ''
for i in 0 .. input.size { for i in 0 .. input.size {
@ -103,7 +102,7 @@ pub fn new(size int) BitField {
return output return output
} }
// frees the memory allocated for the bitfield instance // frees the memory allocated for the bitfield instance.
@[unsafe] @[unsafe]
pub fn (instance &BitField) free() { pub fn (instance &BitField) free() {
unsafe { unsafe {
@ -138,9 +137,8 @@ pub fn (mut instance BitField) clear_bit(bitnr int) {
instance.field[bitslot(bitnr)] &= ~bitmask(bitnr) instance.field[bitslot(bitnr)] &= ~bitmask(bitnr)
} }
// extract returns the value converted from a slice of bit numbers // extract returns the value converted from a slice of bit numbers from 'start' by the length of 'len'.
// from 'start' by the length of 'len'. // For example 0101 . extract(1, 2) => 0b10
// 0101 (1, 2) => 0b10
pub fn (instance BitField) extract(start int, len int) u64 { pub fn (instance BitField) extract(start int, len int) u64 {
// panic? // panic?
if start < 0 { if start < 0 {
@ -153,9 +151,8 @@ pub fn (instance BitField) extract(start int, len int) u64 {
return output return output
} }
// insert sets bit numbers from 'start' to 'len' length with // insert sets bit numbers from 'start' to 'len' length with the value converted from the number 'value'.
// the value converted from the number 'value'. // For example 0000.insert(1, 2, 0b10) => 0100
// 0000 (1, 2, 0b10) => 0100
pub fn (mut instance BitField) insert[T](start int, len int, _value T) { pub fn (mut instance BitField) insert[T](start int, len int, _value T) {
// panic? // panic?
if start < 0 { if start < 0 {
@ -173,9 +170,8 @@ pub fn (mut instance BitField) insert[T](start int, len int, _value T) {
} }
} }
// extract returns the value converted from a slice of bit numbers // extract returns the value converted from a slice of bit numbers from 'start' by the length of 'len'.
// from 'start' by the length of 'len'. // For example 0101.extract_lowest_bits_first(1, 2) => 0b01
// 0101 (1, 2) => 0b01
pub fn (instance BitField) extract_lowest_bits_first(start int, len int) u64 { pub fn (instance BitField) extract_lowest_bits_first(start int, len int) u64 {
// panic? // panic?
if start < 0 { if start < 0 {
@ -188,9 +184,8 @@ pub fn (instance BitField) extract_lowest_bits_first(start int, len int) u64 {
return output return output
} }
// insert sets bit numbers from 'start' to 'len' length with // insert sets bit numbers from 'start' to 'len' length with the value converted from the number 'value'.
// the value converted from the number 'value'. // For example 0000.insert_lowest_bits_first(1, 2, 0b10) => 0010
// 0000 (1, 2, 0b10) => 0010
pub fn (mut instance BitField) insert_lowest_bits_first[T](start int, len int, _value T) { pub fn (mut instance BitField) insert_lowest_bits_first[T](start int, len int, _value T) {
// panic? // panic?
if start < 0 { if start < 0 {
@ -222,8 +217,7 @@ pub fn (mut instance BitField) clear_all() {
} }
} }
// toggle_bit changes the value (from 0 to 1 or from 1 to 0) of bit // toggle_bit changes the value (from 0 to 1 or from 1 to 0) of bit number 'bit_nr'.
// number 'bit_nr'.
@[inline] @[inline]
pub fn (mut instance BitField) toggle_bit(bitnr int) { pub fn (mut instance BitField) toggle_bit(bitnr int) {
if bitnr >= instance.size { if bitnr >= instance.size {
@ -245,7 +239,7 @@ pub fn (mut instance BitField) set_if(cond bool, bitnr int) {
} }
} }
// toggle_bits changes the value (from 0 to 1 or from 1 to 0) of bits // toggle_bits changes the value (from 0 to 1 or from 1 to 0) of bits.
// Example: toggle_bits(1,3,5,7) // Example: toggle_bits(1,3,5,7)
@[inline] @[inline]
pub fn (mut instance BitField) toggle_bits(a ...int) { pub fn (mut instance BitField) toggle_bits(a ...int) {
@ -281,7 +275,7 @@ pub fn (mut instance BitField) clear_bits(a ...int) {
} }
} }
// has test if *at least one* of the bits is set // has test if *at least one* of the bits is set.
// Example: has(1,3,5,7) // Example: has(1,3,5,7)
@[inline] @[inline]
pub fn (mut instance BitField) has(a ...int) bool { pub fn (mut instance BitField) has(a ...int) bool {
@ -296,7 +290,7 @@ pub fn (mut instance BitField) has(a ...int) bool {
return false return false
} }
// all test if *all* of the bits are set // all test if *all* of the bits are set.
// Example: all(1,3,5,7) // Example: all(1,3,5,7)
@[inline] @[inline]
pub fn (mut instance BitField) all(a ...int) bool { pub fn (mut instance BitField) all(a ...int) bool {
@ -311,9 +305,8 @@ pub fn (mut instance BitField) all(a ...int) bool {
return true return true
} }
// bf_and performs logical AND operation on every pair of bits from 'input1' and // bf_and performs logical AND operation on every pair of bits from 'input1' and 'input2'.
// 'input2' and returns the result as a new array. If inputs differ in size, // It returns the result as a new array. If inputs differ in size, the tail of the longer one is ignored.
// the tail of the longer one is ignored.
pub fn bf_and(input1 BitField, input2 BitField) BitField { pub fn bf_and(input1 BitField, input2 BitField) BitField {
size := min(input1.size, input2.size) size := min(input1.size, input2.size)
bitnslots := zbitnslots(size) bitnslots := zbitnslots(size)
@ -337,9 +330,8 @@ pub fn bf_not(input BitField) BitField {
return output return output
} }
// bf_or performs logical OR operation on every pair of bits from 'input1' and // bf_or performs logical OR operation on every pair of bits from 'input1' and 'input2'.
// 'input2' and returns the result as a new array. If inputs differ in size, // It returns the result as a new array. If inputs differ in size, the tail of the longer one is ignored.
// the tail of the longer one is ignored.
pub fn bf_or(input1 BitField, input2 BitField) BitField { pub fn bf_or(input1 BitField, input2 BitField) BitField {
size := min(input1.size, input2.size) size := min(input1.size, input2.size)
bitnslots := zbitnslots(size) bitnslots := zbitnslots(size)
@ -351,9 +343,8 @@ pub fn bf_or(input1 BitField, input2 BitField) BitField {
return output return output
} }
// bf_xor perform logical XOR operation on every pair of bits from 'input1' and // bf_xor perform logical XOR operation on every pair of bits from 'input1' and 'input2'.
// 'input2' and returns the result as a new array. If inputs differ in size, // It returns the result as a new array. If inputs differ in size, the tail of the longer one is ignored.
// the tail of the longer one is ignored.
pub fn bf_xor(input1 BitField, input2 BitField) BitField { pub fn bf_xor(input1 BitField, input2 BitField) BitField {
size := min(input1.size, input2.size) size := min(input1.size, input2.size)
bitnslots := zbitnslots(size) bitnslots := zbitnslots(size)
@ -420,7 +411,7 @@ pub fn (instance BitField) clone() BitField {
return output return output
} }
// == compares 2 bitfields, and returns true when they are equal // == compares 2 bitfields, and returns true when they are equal.
pub fn (a BitField) == (b BitField) bool { pub fn (a BitField) == (b BitField) bool {
if a.size != b.size { if a.size != b.size {
return false return false
@ -461,8 +452,8 @@ pub fn hamming(input1 BitField, input2 BitField) int {
return input_xored.pop_count() return input_xored.pop_count()
} }
// pos checks if the array contains a sub-array 'needle' and returns its // pos checks if the array contains a sub-array 'needle'.
// position if it does, -1 if it does not, and -2 on error. // It returns its position if it does, -1 if it does not, and -2 on error.
pub fn (haystack BitField) pos(needle BitField) int { pub fn (haystack BitField) pos(needle BitField) int {
heystack_size := haystack.size heystack_size := haystack.size
needle_size := needle.size needle_size := needle.size
@ -482,8 +473,7 @@ pub fn (haystack BitField) pos(needle BitField) int {
return -1 return -1
} }
// slice returns a sub-array of bits between 'start_bit_nr' (included) and // slice returns a sub-array of bits between 'start_bit_nr' (included) and 'end_bit_nr' (excluded).
// 'end_bit_nr' (excluded).
pub fn (input BitField) slice(_start int, _end int) BitField { pub fn (input BitField) slice(_start int, _end int) BitField {
// boundary checks // boundary checks
mut start := _start mut start := _start
@ -536,8 +526,7 @@ pub fn (input BitField) slice(_start int, _end int) BitField {
return output return output
} }
// reverse reverses the order of bits in the array (swap the first with the // reverse reverses the order of bits in the array (swap the first with the last, the second with the last but one and so on).
// last, the second with the last but one and so on).
pub fn (instance BitField) reverse() BitField { pub fn (instance BitField) reverse() BitField {
size := instance.size size := instance.size
bitnslots := zbitnslots(size) bitnslots := zbitnslots(size)
@ -574,8 +563,7 @@ pub fn (mut instance BitField) resize(new_size int) {
} }
} }
// rotate circular-shifts the bits by 'offset' positions (move // rotate circular-shifts the bits by 'offset' positions (move 'offset' bit to 0, 'offset+1' bit to 1, and so on).
// 'offset' bit to 0, 'offset+1' bit to 1, and so on).
pub fn (instance BitField) rotate(offset int) BitField { pub fn (instance BitField) rotate(offset int) BitField {
/* /*
* *

2
vlib/build/build.v
View File

@ -115,7 +115,7 @@ pub fn (mut context BuildContext) exec(name string) {
} }
} }
// exec runs the given task and its dependencies // exec runs the given task and its dependencies.
pub fn (mut task Task) exec(mut context BuildContext) { pub fn (mut task Task) exec(mut context BuildContext) {
if task.did_run && !task.repeatable { if task.did_run && !task.repeatable {
println(': ${task.name} (skipped)') println(': ${task.name} (skipped)')