refine notes on cast

src/common/src/types/to_text.rs

@@ -18,12 +18,22 @@ use std::num::FpCategory;
 use super::{DataType, DatumRef, ScalarRefImpl};
 use crate::dispatch_scalar_ref_variants;
 
-/// Converts `ScalarRef` to text format.
-/// This is the implementation for casting to varchar, and pgwire "TEXT" format.
+/// Converts `ScalarRef` to pgwire "TEXT" format.
+///
+/// ## Relationship with casting to varchar
+///
+/// For most types, this is also the implementation for casting to varchar, but there are exceptions.
+/// e.g., The TEXT format for boolean is `t` / `f` while they cast to varchar `true` / `false`.
+/// - <https://github.com/postgres/postgres/blob/REL_16_3/src/include/catalog/pg_cast.dat#L438-L439>
+/// - <https://www.postgresql.org/docs/16/sql-createcast.html#:~:text=A%20small%20number%20of%20the%20built%2Din%20types%20do%20indeed%20have%20different%20behaviors%20for%20conversions%2C%20mostly%20because%20of%20requirements%20of%20the%20SQL%20standard>
+///
+/// ## Relationship with `ToString`/`Display`
 ///
 /// For some types, the implementation diverge from Rust's standard `ToString`/`Display`,
 /// to match PostgreSQL's representation.
 ///
+/// ---
+///
 /// FIXME: `ToText` should depend on a lot of other stuff
 /// but we have not implemented them yet: timezone, date style, interval style, bytea output, etc
 pub trait ToText {

src/expr/impl/src/scalar/cast.rs

@@ -147,8 +147,8 @@ pub fn int_to_bool(input: i32) -> bool {
     input != 0
 }
 
-// For most of the types, cast them to varchar is similar to return their text format.
-// So we use this function to cast type to varchar.
+/// For most of the types, cast them to varchar is the same as their pgwire "TEXT" format.
+/// So we use `ToText` to cast type to varchar.
 #[function("cast(*int) -> varchar")]
 #[function("cast(decimal) -> varchar")]
 #[function("cast(*float) -> varchar")]
@@ -177,7 +177,7 @@ pub fn bool_to_varchar(input: bool, writer: &mut impl Write) {
         .unwrap();
 }
 
-/// `bool_out` is different from `general_to_string<bool>` to produce a single char. `PostgreSQL`
+/// `bool_out` is different from `cast(boolean) -> varchar` to produce a single char. `PostgreSQL`
 /// uses different variants of bool-to-string in different situations.
 #[function("bool_out(boolean) -> varchar")]
 pub fn bool_out(input: bool, writer: &mut impl Write) {