io: add missing documentation and edit existing ones (#17105)

vlib/io/buffered_reader.v

@@ -1,6 +1,6 @@
 module io
 
-// BufferedReader provides a buffered interface for a reader
+// BufferedReader provides a buffered interface for a reader.
 pub struct BufferedReader {
 mut:
 	reader Reader
@@ -13,14 +13,14 @@ pub mut:
 	end_of_stream bool // whether we reached the end of the upstream reader
 }
 
-// BufferedReaderConfig are options that can be given to a reader
+// BufferedReaderConfig are options that can be given to a buffered reader.
 pub struct BufferedReaderConfig {
 	reader  Reader
 	cap     int = 128 * 1024 // large for fast reading of big(ish) files
 	retries int = 2 // how many times to retry before assuming the stream ended
 }
 
-// new_buffered_reader creates new BufferedReader
+// new_buffered_reader creates a new BufferedReader.
 pub fn new_buffered_reader(o BufferedReaderConfig) &BufferedReader {
 	if o.cap <= 0 {
 		panic('new_buffered_reader should be called with a positive `cap`')
@@ -35,7 +35,7 @@ pub fn new_buffered_reader(o BufferedReaderConfig) &BufferedReader {
 	return r
 }
 
-// read fufills the Reader interface
+// read fufills the Reader interface.
 pub fn (mut r BufferedReader) read(mut buf []u8) !int {
 	if r.end_of_stream {
 		return Eof{}
@@ -58,6 +58,7 @@ pub fn (mut r BufferedReader) read(mut buf []u8) !int {
 	return read
 }
 
+// free deallocates the memory for a buffered reader's internal buffer.
 pub fn (mut r BufferedReader) free() {
 	unsafe {
 		r.buf.free()
@@ -65,7 +66,7 @@ pub fn (mut r BufferedReader) free() {
 }
 
 // fill_buffer attempts to refill the internal buffer
-// and returns whether it got any data
+// and returns whether it got any data.
 fn (mut r BufferedReader) fill_buffer() bool {
 	if r.end_of_stream {
 		// we know we have already reached the end of stream
@@ -94,19 +95,19 @@ fn (mut r BufferedReader) fill_buffer() bool {
 	return true
 }
 
-// needs_fill returns whether the buffer needs refilling
+// needs_fill returns whether the buffer needs refilling.
 fn (r BufferedReader) needs_fill() bool {
 	return r.offset >= r.len
 }
 
-// end_of_stream returns whether the end of the stream was reached
+// end_of_stream returns whether the end of the stream was reached.
 pub fn (r BufferedReader) end_of_stream() bool {
 	return r.end_of_stream
 }
 
 // read_line attempts to read a line from the buffered reader
 // it will read until it finds a new line character (\n) or
-// the end of stream
+// the end of stream.
 pub fn (mut r BufferedReader) read_line() !string {
 	if r.end_of_stream {
 		return error('none')

vlib/io/io.v

@@ -4,6 +4,10 @@ const (
 	buf_max_len = 1024
 )
 
+// cp copies from `src` to `dst` by allocating
+// a maximum of 1024 bytes buffer for reading
+// until either EOF is reached on `src` or an error occurs.
+// An error is returned if an error is encountered during write.
 pub fn cp(mut src Reader, mut dst Writer) ! {
 	mut buf := []u8{len: io.buf_max_len}
 	for {

vlib/io/reader.v

@@ -19,7 +19,7 @@ fn (err NotExpected) code() int {
 	return err.code
 }
 
-// Reader represents a stream of data that can be read
+// Reader represents a stream of data that can be read.
 pub interface Reader {
 	// read reads up to buf.len bytes and places
 	// them into buf.
@@ -35,7 +35,7 @@ const (
 )
 
 // ReadAllConfig allows options to be passed for the behaviour
-// of read_all
+// of read_all.
 pub struct ReadAllConfig {
 	read_to_end_of_stream bool
 mut:
@@ -43,7 +43,7 @@ mut:
 }
 
 // read_all reads all bytes from a reader until either a 0 length read
-// or if read_to_end_of_stream is true then the end of the stream (`none`)
+// or if read_to_end_of_stream is true then the end of the stream (`none`).
 pub fn read_all(config ReadAllConfig) ![]u8 {
 	mut r := config.reader
 	read_till_eof := config.read_to_end_of_stream
@@ -64,7 +64,7 @@ pub fn read_all(config ReadAllConfig) ![]u8 {
 }
 
 // read_any reads any available bytes from a reader
-// (until the reader returns a read of 0 length)
+// (until the reader returns a read of 0 length).
 pub fn read_any(mut r Reader) ![]u8 {
 	mut b := []u8{len: io.read_all_len}
 	mut read := 0
@@ -81,7 +81,7 @@ pub fn read_any(mut r Reader) ![]u8 {
 	return b[..read]
 }
 
-// RandomReader represents a stream of data that can be read from at a random location
+// RandomReader represents a stream of readable data from at a random location.
 pub interface RandomReader {
 	read_from(pos u64, mut buf []u8) !int
 }

vlib/io/readerwriter.v

@@ -1,29 +1,34 @@
 module io
 
-// ReaderWriter represents a stream that can be read from and wrote to
+// ReaderWriter represents a stream that can be read and written.
 pub interface ReaderWriter {
 	Reader
 	Writer
 }
 
 // ReaderWriterImpl is a ReaderWriter that can be made from
-// a separate reader and writer (see fn make_readerwriter)
+// a separate reader and writer (see fn make_readerwriter).
 struct ReaderWriterImpl {
 mut:
 	r Reader
 	w Writer
 }
 
+// read reads up to `buf.len` bytes into `buf`. It returns
+// the number of bytes read or any error encountered.
 pub fn (mut r ReaderWriterImpl) read(mut buf []u8) !int {
 	return r.r.read(mut buf)
 }
 
+// write writes `buf.len` bytes from `buf` to the underlying
+// data stream. It returns the number of bytes written or any error
+// encountered.
 pub fn (mut r ReaderWriterImpl) write(buf []u8) !int {
 	return r.w.write(buf)
 }
 
 // make_readerwriter takes a rstream and a wstream and makes
-// an rwstream with them
+// an rwstream with them.
 pub fn make_readerwriter(r Reader, w Writer) ReaderWriterImpl {
 	return ReaderWriterImpl{
 		r: r

vlib/io/util/util.v

@@ -13,7 +13,7 @@ pub struct TempFileOptions {
 	pattern string
 }
 
-// temp_file returns an uniquely named, open, writable, `os.File` and it's path
+// temp_file returns a uniquely named, open, writable, `os.File` and it's path.
 pub fn temp_file(tfo TempFileOptions) !(os.File, string) {
 	mut d := tfo.path
 	if d == '' {
@@ -50,7 +50,7 @@ fn error_for_temporary_folder(fn_name string, d string) !string {
 	return error('${fn_name} could not create temporary directory "${d}". Please ensure you have write permissions for it.')
 }
 
-// temp_dir returns an uniquely named, writable, directory path
+// temp_dir returns a uniquely named, writable, directory path.
 pub fn temp_dir(tdo TempFileOptions) !string {
 	mut d := tdo.path
 	if d == '' {

vlib/io/writer.v

@@ -1,13 +1,14 @@
 module io
 
-// Writer represents a stream of data that can be written to
+// Writer is the interface that wraps the `write` method, which
+// writes `buf.len` bytes to the underlying data stream.
 pub interface Writer {
 mut:
 	write(buf []u8) !int
 }
 
-// RandomWriter represents a stream of data that can be written to
+// RandomWriter is the interface that wraps the `write_to` method,
-// at a random pos
+// which writes `buf.len` bytes to the underlying data stream at a random `pos`.
 pub interface RandomWriter {
 	write_to(pos u64, buf []u8) !int
 }