From 21b17fe23419749d568b24a5bc39e6a00cb85eca Mon Sep 17 00:00:00 2001 From: Nahua Date: Wed, 25 Jan 2023 21:03:20 +0100 Subject: [PATCH] io: add missing documentation and edit existing ones (#17105) --- vlib/io/buffered_reader.v | 17 +++++++++-------- vlib/io/io.v | 4 ++++ vlib/io/reader.v | 10 +++++----- vlib/io/readerwriter.v | 11 ++++++++--- vlib/io/util/util.v | 4 ++-- vlib/io/writer.v | 7 ++++--- 6 files changed, 32 insertions(+), 21 deletions(-) diff --git a/vlib/io/buffered_reader.v b/vlib/io/buffered_reader.v index c92302de76..911acfc6c5 100644 --- a/vlib/io/buffered_reader.v +++ b/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') diff --git a/vlib/io/io.v b/vlib/io/io.v index 56ef4d7182..24066f3c36 100644 --- a/vlib/io/io.v +++ b/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 { diff --git a/vlib/io/reader.v b/vlib/io/reader.v index 570dad83c0..58f0186ec9 100644 --- a/vlib/io/reader.v +++ b/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 } diff --git a/vlib/io/readerwriter.v b/vlib/io/readerwriter.v index 7867781bb8..e079517654 100644 --- a/vlib/io/readerwriter.v +++ b/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 diff --git a/vlib/io/util/util.v b/vlib/io/util/util.v index bace828397..f8252cf6bb 100644 --- a/vlib/io/util/util.v +++ b/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 == '' { diff --git a/vlib/io/writer.v b/vlib/io/writer.v index be0d93f71c..9223d3afbd 100644 --- a/vlib/io/writer.v +++ b/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 -// at a random pos +// RandomWriter is the interface that wraps the `write_to` method, +// which writes `buf.len` bytes to the underlying data stream at a random `pos`. pub interface RandomWriter { write_to(pos u64, buf []u8) !int }