[Variant] Remove dead code, add comments (#7861)

# Which issue does this PR close?

We generally require a GitHub issue to be filed for all bug fixes and
enhancements and this helps us generate change logs for our releases.
You can link an issue to this PR using the GitHub syntax.

- Part of #6736 

# Rationale for this change

The `allow_deadcode` has bothered me while reviewing PRs and it also is
hiding actually dead code

# What changes are included in this PR?

1. Remove clippy annotations to allow dead code
2. Remove code clippy found as dead
3. Add some docs (drive by docing)

# Are these changes tested?

By CI

# Are there any user-facing changes?

Just some more docs

Author: alamb

parquet-variant/src/decoder.rs

@@ -22,12 +22,15 @@ use crate::ShortString;
 use arrow_schema::ArrowError;
 use chrono::{DateTime, Duration, NaiveDate, NaiveDateTime, Utc};
 
-use std::array::TryFromSliceError;
 use std::num::TryFromIntError;
 
-// Makes the code a bit more readable
-pub(crate) const VARIANT_VALUE_HEADER_BYTES: usize = 1;
-
+/// The basic type of a [`Variant`] value, encoded in the first two bits of the
+/// header byte.
+///
+/// See the [Variant Encoding specification] for details
+///
+/// [`Variant`]: crate::Variant
+/// [Variant Encoding specification]: https://github.com/apache/parquet-format/blob/master/VariantEncoding.md#encoding-types
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum VariantBasicType {
     Primitive = 0,
@@ -36,6 +39,13 @@ pub enum VariantBasicType {
     Array = 3,
 }
 
+/// The type of [`VariantBasicType::Primitive`], for a primitive [`Variant`]
+/// value.
+///
+/// See the [Variant Encoding specification] for details
+///
+/// [`Variant`]: crate::Variant
+/// [Variant Encoding specification]: https://github.com/apache/parquet-format/blob/master/VariantEncoding.md#encoding-types
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum VariantPrimitiveType {
     Null = 0,
@@ -196,11 +206,6 @@ pub(crate) fn get_primitive_type(metadata: u8) -> Result<VariantPrimitiveType, A
     VariantPrimitiveType::try_from(metadata >> 2)
 }
 
-/// To be used in `map_err` when unpacking an integer from a slice of bytes.
-fn map_try_from_slice_error(e: TryFromSliceError) -> ArrowError {
-    ArrowError::InvalidArgumentError(e.to_string())
-}
-
 /// Decodes an Int8 from the value section of a variant.
 pub(crate) fn decode_int8(data: &[u8]) -> Result<i8, ArrowError> {
     Ok(i8::from_le_bytes(array_from_slice(data, 0)?))

parquet-variant/src/lib.rs

@@ -27,16 +27,12 @@
 //!
 //! [Variant issue]: https://github.com/apache/arrow-rs/issues/6736
 
-// TODO: dead code removal
-#[allow(dead_code)]
-mod decoder;
-mod variant;
-// TODO: dead code removal
 mod builder;
+mod decoder;
 mod from_json;
 mod to_json;
-#[allow(dead_code)]
 mod utils;
+mod variant;
 
 pub use builder::*;
 pub use from_json::json_to_variant;