dan/oxc
1
0
Fork 0
mirror of https://github.com/danbulant/oxc synced 2026-05-19 20:28:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(codegen): correct and reformat doc comments for CodeBuffer (#6504)

Browse source 
Comment about `take_source_text` was erroneous. Clean up and reformat other doc comments.
This commit is contained in:
overlookmotel 2024-10-13 11:10:09 +00:00
parent 6f2253886d
commit c8fa2eb17a
1 changed files with 54 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

114
crates/oxc_codegen/src/code_buffer.rs
View file

@ -2,12 +2,12 @@ use std::mem;
/// A string builder for constructing source code. /// A string builder for constructing source code.
/// ///
/// `CodeBuffer` provides safe abstractions over a byte array.
/// Essentially same as `String` but with additional methods.
/// ///
/// `CodeBuffer` provides safe abstractions over a byte array, allowing for /// Use one of the various `print_*` methods to add text into the buffer.
/// a compact byte-array representation without soundness holes. /// When you are done, call [`take_source_text`] or `String::from(code_buffer)`
/// /// to extract the final [`String`].
/// Use one of the various `print_*` methods to add text into a buffer. When you
/// are done, call [`take_source_text`] to extract the final [`String`].
/// ///
/// # Example /// # Example
/// ``` /// ```
@ -53,31 +53,31 @@ impl CodeBuffer {
/// Create a new, empty `CodeBuffer` with the specified capacity. /// Create a new, empty `CodeBuffer` with the specified capacity.
/// ///
/// The buffer will be able to hold at least `capacity` bytes without /// The buffer will be able to hold at least `capacity` bytes without reallocating.
/// reallocating. This method is allowed to allocate for more bytes than /// This method is allowed to allocate for more bytes than `capacity`.
/// `capacity`. If `capacity` is 0, the buffer will not allocate. /// If `capacity` is 0, the buffer will not allocate.
/// ///
/// It is important to note that although the returned buffer has the /// It is important to note that although the returned buffer has the
/// minimum *capacity* specified, the buffer will have a zero *length*. /// minimum *capacity* specified, the buffer will have a zero *length*.
/// ///
/// # Panics /// # Panics
/// ///
/// Panics if the new capacity exceeds `isize::MAX` _bytes_. /// Panics if the new capacity exceeds `isize::MAX` bytes.
#[inline] #[inline]
pub fn with_capacity(capacity: usize) -> Self { pub fn with_capacity(capacity: usize) -> Self {
Self { buf: Vec::with_capacity(capacity) } Self { buf: Vec::with_capacity(capacity) }
} }
/// Returns the number of bytes in this buffer. /// Returns the number of bytes in the buffer.
/// ///
/// This is _not_ the same as the number of characters in the buffer, since /// This is *not* the same as the number of characters in the buffer,
/// non-ASCII characters require multiple bytes. /// since non-ASCII characters require multiple bytes.
#[inline] #[inline]
pub fn len(&self) -> usize { pub fn len(&self) -> usize {
self.buf.len() self.buf.len()
} }
/// Returns `true` if this buffer contains no characters. /// Returns `true` if the buffer contains no characters.
/// ///
/// # Example /// # Example
/// ``` /// ```
@ -93,15 +93,15 @@ impl CodeBuffer {
self.buf.is_empty() self.buf.is_empty()
} }
/// Reserves capacity for at least `additional` more characters in the given /// Reserves capacity for at least `additional` more bytes in the buffer.
/// `CodeBuffer`. The buffer may reserve more space to speculatively avoid ///
/// frequent reallocations. After calling `reserve`, capacity will be /// The buffer may reserve more space to speculatively avoid frequent reallocations.
/// greater than or equal to `self.len() + additional`. Does nothing if /// After calling `reserve`, capacity will be greater than or equal to `self.len() + additional`.
/// capacity is already sufficient. /// Does nothing if capacity is already sufficient.
/// ///
/// # Panics /// # Panics
/// ///
/// Panics if the new capacity exceeds `isize::MAX` _bytes_. /// Panics if the new capacity exceeds `isize::MAX` bytes.
/// ///
/// # Example /// # Example
/// ``` /// ```
@ -115,8 +115,9 @@ impl CodeBuffer {
} }
/// Peek the `n`th character from the end of the buffer. /// Peek the `n`th character from the end of the buffer.
/// When `n` is zero, the last character is returned. Returns [`None`] if ///
/// `n` exceeds the length of the buffer. /// When `n` is zero, the last character is returned.
/// Returns [`None`] if `n` exceeds the length of the buffer.
/// ///
/// # Example /// # Example
/// ``` /// ```
@ -131,14 +132,14 @@ impl CodeBuffer {
#[inline] #[inline]
#[must_use = "Peeking is pointless if the peeked char isn't used"] #[must_use = "Peeking is pointless if the peeked char isn't used"]
pub fn peek_nth_back(&self, n: usize) -> Option<char> { pub fn peek_nth_back(&self, n: usize) -> Option<char> {
// SAFETY: `buf` is a valid UTF-8 string because of invariants upheld by CodeBuffer // SAFETY: All methods of `CodeBuffer` ensure `buf` is valid UTF-8
unsafe { std::str::from_utf8_unchecked(&self.buf) }.chars().nth_back(n) unsafe { std::str::from_utf8_unchecked(&self.buf) }.chars().nth_back(n)
} }
/// Push a single ASCII character into the buffer /// Push a single ASCII byte into the buffer.
/// ///
/// # Panics /// # Panics
/// If `ch` is not a valid UTF-8 code point in the ASCII range (`0 - 0x7F`). /// If `b` is not an ASCII byte (`0 - 0x7F`).
/// ///
/// # Example /// # Example
/// ``` /// ```
@ -160,24 +161,21 @@ impl CodeBuffer {
self.buf.push(b); self.buf.push(b);
} }
/// Print a byte without checking that this buffer still represents a valid /// Push a byte to the buffer, without checking that the buffer still represents a valid
/// UTF-8 string. /// UTF-8 string.
/// ///
/// If you are looking to print a byte you know is valid ASCII, prefer /// If you are looking to print a byte you know is valid ASCII, prefer [`print_ascii_byte`].
/// [`print_ascii_byte`]. If you are not certain, you may use [`print_char`] /// If you are not certain, you may use [`print_char`] as a safe alternative.
/// as a safe alternative.
/// ///
/// # Safety /// # SAFETY
/// The caller must ensure that, after 1 or more sequential calls, this /// The caller must ensure that, after 1 or more sequential calls, the buffer represents
/// buffer represents a valid UTF-8 string. /// a valid UTF-8 string.
/// ///
/// It is safe for a single call to temporarily result in invalid UTF-8, as /// It is safe for a single call to temporarily result in invalid UTF-8, as long as
/// long as UTF-8 integrity is restored before calls to any other `print` /// UTF-8 integrity is restored before calls to any other `print_*` method or
/// method or [`take_source_text`]. This lets you, for example, print an /// [`take_source_text`]. This lets you, for example, print an 4-byte Unicode character
/// 8-byte code point using 4 separate calls to this method. /// using 4 separate calls to this method. However, consider using [`print_unchecked`]
/// /// instead for that use case.
/// If you find yourself in such a scenario, consider using
/// [`print_unchecked`] instead.
/// ///
/// # Example /// # Example
/// ``` /// ```
@ -207,12 +205,11 @@ impl CodeBuffer {
self.buf.push(ch); self.buf.push(ch);
} }
/// Print a single Unicode character into the buffer. /// Push a single Unicode character into the buffer.
/// ///
/// When pushing multiple characters, consider choosing [`print_str`] over /// When pushing multiple characters, consider choosing [`print_str`] over this method
/// this method since it's much more efficient. If you really want to insert /// since it's much more efficient. If you really want to insert only a single character
/// only a single character and you're certain it's ASCII, consider using /// and you're certain it's ASCII, consider using [`print_ascii_byte`].
/// [`print_ascii_byte`].
/// ///
/// # Example /// # Example
/// ``` /// ```
@ -234,7 +231,7 @@ impl CodeBuffer {
self.buf.extend(ch.encode_utf8(&mut b).as_bytes()); self.buf.extend(ch.encode_utf8(&mut b).as_bytes());
} }
/// Push a string into this the buffer. /// Push a string into the buffer.
/// ///
/// # Example /// # Example
/// ``` /// ```
@ -250,7 +247,7 @@ impl CodeBuffer {
/// Push a sequence of ASCII characters into the buffer. /// Push a sequence of ASCII characters into the buffer.
/// ///
/// # Panics /// # Panics
/// If any byte in the iterator is not valid ASCII. /// Panics if any byte in the iterator is not ASCII.
/// ///
/// # Example /// # Example
/// ``` /// ```
@ -272,26 +269,25 @@ impl CodeBuffer {
} }
} }
/// Print a sequence of bytes without checking that this buffer still /// Print a sequence of bytes without checking that the buffer still
/// represents a valid UTF-8 string. /// represents a valid UTF-8 string.
/// ///
/// # Safety /// # Safety
/// ///
/// The caller must ensure that, after being called, this buffer represents /// The caller must ensure that, after this method call, the buffer represents
/// a valid UTF-8 string. In practice, this means only two cases are valid: /// a valid UTF-8 string. In practice, this means only two cases are valid:
/// ///
/// 1. Both the buffer and the byte sequence are valid UTF-8, /// 1. Both the buffer and the byte sequence are valid UTF-8,
/// 2. The buffer became invalid after a call to [`print_byte_unchecked`] and `bytes` /// 2. The buffer became invalid after a call to [`print_byte_unchecked`] and `bytes` completes
/// completes any incomplete code points, returning the buffer to a valid /// any incomplete Unicode characters, returning the buffer to a valid state.
/// state.
/// ///
/// # Example /// # Example
/// ``` /// ```
/// use oxc_codegen::CodeBuffer; /// use oxc_codegen::CodeBuffer;
/// let mut code = CodeBuffer::new(); /// let mut code = CodeBuffer::new();
/// ///
/// // Indent to a dynamic level. Sound because all elements in this /// // Indent to a dynamic level.
/// // iterator are valid 1-byte UTF-8 code points (ASCII). /// // Sound because all elements in this iterator are ASCII characters.
/// unsafe { /// unsafe {
/// code.print_unchecked(std::iter::repeat(b' ').take(4)); /// code.print_unchecked(std::iter::repeat(b' ').take(4));
/// } /// }
@ -306,7 +302,7 @@ impl CodeBuffer {
self.buf.extend(bytes); self.buf.extend(bytes);
} }
/// Get contents of `CodeBuffer` as a byte slice. /// Get contents of buffer as a byte slice.
/// ///
/// # Example /// # Example
/// ``` /// ```
@ -320,14 +316,12 @@ impl CodeBuffer {
&self.buf &self.buf
} }
/// Convert a `CodeBuffer` into a string of source code, leaving its /// Convert a buffer into a string of source code, leaving its internal buffer empty.
/// internal buffer empty and finalizing the codegen process.
/// ///
/// It is safe to re-use a buffer after calling this method. Its contents /// It is safe to re-use a `CodeBuffer` after calling this method, but there is little benefit
/// will be emptied out, but all memory resources are retained and in a /// to doing so, as the `CodeBuffer` will be left in an empty state with no backing allocation.
/// valid state. You may use [`String::from`] if you don't intend on ///
/// re-using the buffer. It simply calls this method and drops the /// You may alternatively use `String::from(code_buffer)`, which may be slightly more efficient.
/// `CodeBuffer` afterwards.
/// ///
/// # Example /// # Example
/// ``` /// ```