add docstring

Author: lovasoa

src/ast/value.rs

@@ -30,7 +30,42 @@ use crate::{ast::Ident, tokenizer::Span};
 #[cfg(feature = "visitor")]
 use sqlparser_derive::{Visit, VisitMut};
 
-/// Primitive SQL values such as number and string
+
+
+/// Wraps a primitive SQL [`Value`]  with its [`Span`] location
+///
+/// # Example: create a `ValueWithSpan` from a `Value`
+/// ```
+/// # use sqlparser::ast::{Value, ValueWithSpan};
+/// # use sqlparser::tokenizer::{Location, Span};
+/// let value = Value::SingleQuotedString(String::from("endpoint"));
+/// // from line 1, column 1 to line 1, column 7
+/// let span = Span::new(Location::new(1, 1), Location::new(1, 7));
+/// let value_with_span = value.with_span(span);
+/// ```
+///
+/// # Example: create a `ValueWithSpan` from a `Value` with an empty span
+///
+/// You can call [`Value::with_empty_span`] to create a `ValueWithSpan` with an empty span
+/// ```
+/// # use sqlparser::ast::{Value, ValueWithSpan};
+/// # use sqlparser::tokenizer::{Location, Span};
+/// let value = Value::SingleQuotedString(String::from("endpoint"));
+/// let value_with_span = value.with_empty_span();
+/// assert_eq!(value_with_span.span, Span::empty());
+/// ```
+///
+/// You can also use the [`From`] trait to convert  `ValueWithSpan` to/from `Value`s
+/// ```
+/// # use sqlparser::ast::{Value, ValueWithSpan};
+/// # use sqlparser::tokenizer::{Location, Span};
+/// let value = Value::SingleQuotedString(String::from("endpoint"));
+/// // converting `Value` to `ValueWithSpan` results in an empty span
+/// let value_with_span: ValueWithSpan = value.into();
+/// assert_eq!(value_with_span.span, Span::empty());
+/// // convert back to `Value`
+/// let value: Value = value_with_span.into();
+/// ```
 #[derive(Debug, Clone, Eq)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[cfg_attr(feature = "visitor", derive(Visit, VisitMut))]