docs + cleanup

Author: dishmaker

der/src/asn1.rs

@@ -42,7 +42,6 @@ pub use self::{
     },
     bit_string::{BitStringIter, BitStringRef},
     choice::Choice,
-    //context_specific::{ContextSpecific, ContextSpecificRef},
     context_specific::{
         ContextSpecificExplicit, ContextSpecificExplicitRef, ContextSpecificImplicit,
         ContextSpecificImplicitRef,

der/src/asn1/any_custom_class.rs

@@ -1,3 +1,5 @@
+//! Less strict Context-specific, Application or Private field.
+
 use crate::{
     Class, Decode, DecodeValue, Encode, EncodeValue, Error, Header, Length, Reader, Tag, TagNumber,
     Tagged, Writer,
@@ -56,7 +58,7 @@ where
         tag_number: TagNumber,
         reader: &mut R,
     ) -> Result<Option<Self>, T::Error> {
-        decode_peeking(reader, class, tag_number, |reader| {
+        peek_decode_optional(reader, class, tag_number, |reader| {
             Self::decode_checked(class, tag_number, reader)
         })
     }
@@ -94,7 +96,7 @@ where
         tag_number: TagNumber,
         reader: &mut R,
     ) -> Result<Option<Self>, T::Error> {
-        decode_peeking::<_, _, T::Error, _>(reader, class, tag_number, |reader| {
+        peek_decode_optional::<_, _, T::Error, _>(reader, class, tag_number, |reader| {
             Self::decode_checked(class, tag_number, reader)
         })
     }
@@ -201,7 +203,7 @@ impl<T> Tagged for AnyCustomClassImplicit<T> {
 
 /// Attempt to decode a custom class-tagged field with the given
 /// helper callback.
-fn decode_peeking<'a, F, R: Reader<'a>, E, T>(
+fn peek_decode_optional<'a, F, R: Reader<'a>, E, T>(
     reader: &mut R,
     expected_class: Class,
     expected_number: TagNumber,
@@ -234,6 +236,8 @@ fn is_unskippable_tag(tag: Tag, expected_class: Class, expected_number: TagNumbe
         Class::Application => tag.number() > expected_number,
         Class::ContextSpecific => tag.number() > expected_number,
         Class::Private => tag.number() != expected_number,
+
+        // probably unreachable
         Class::Universal => tag.number() != expected_number,
     }
 }

der/src/asn1/custom_class.rs

@@ -1,3 +1,5 @@
+//! Context-specific, Application or Private field.
+
 use super::any_custom_class::{
     expected_tag_constructed, AnyCustomClassExplicit, AnyCustomClassImplicit,
 };
@@ -9,20 +11,32 @@ use crate::{
 };
 use core::cmp::Ordering;
 
-/// Application, Context-specific or Private class field which wraps an owned inner value.
+/// Application, Context-specific or Private class field which wraps an owned inner value `T`.
 ///
 /// This type decodes/encodes a field which is specific to a particular context
-/// and is identified by a [`TagNumber`].
+/// and is identified by a [`TagNumber`] in `TAG` generic parameter.
+///
+/// - Encodes: always with `TAG` and `CLASS` generic parameter, with inner tag and value.
+///
+/// - Decodes: only if `TAG` and `CLASS` generic parameter matches data.
+///
+/// Note that only 2 most significant bits of `CLASS` are used.
 #[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
 pub struct CustomClassExplicit<const TAG: u16, T, const CLASS: u8> {
     /// Value of the field.
     pub value: T,
 }
 
-/// Application, Context-specific or Private class field which wraps an owned inner value.
+/// Application, Context-specific or Private class field which wraps an owned inner value `T`.
 ///
 /// This type decodes/encodes a field which is specific to a particular context
-/// and is identified by a [`TagNumber`].
+/// and is identified by a [`TagNumber`] in `TAG` generic parameter.
+///
+/// - Encodes: always with `TAG` and `CLASS` generic parameter, with inner value only (implicit, without inner tag).
+///
+/// - Decodes: only if `TAG` and `CLASS` generic parameter matches data.
+///
+/// Note that only 2 most significant bits of `CLASS` are used.
 #[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
 pub struct CustomClassImplicit<const TAG: u16, T, const CLASS: u8> {
     /// Value of the field.

der/src/asn1/private.rs

@@ -20,56 +20,6 @@ pub type PrivateExplicitRef<'a, const TAG: u16, T> =
 pub type PrivateImplicitRef<'a, const TAG: u16, T> =
     CustomClassImplicitRef<'a, TAG, T, CLASS_PRIVATE>;
 
-// /// Private field reference.
-// ///
-// /// This type encodes a field which is whose meaning is specific to a given
-// /// enterprise and is identified by a [`TagNumber`].
-// #[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
-// pub struct PrivateRef<'a, T> {
-//     /// Private tag number sans the leading `0b11000000` class
-//     /// identifier bit and `0b100000` constructed flag.
-//     pub tag_number: TagNumber,
-
-//     /// Tag mode: `EXPLICIT` VS `IMPLICIT`.
-//     pub tag_mode: TagMode,
-
-//     /// Value of the field.
-//     pub value: &'a T,
-// }
-
-// impl<'a, T> PrivateRef<'a, T> {
-//     /// Convert to a [`Private`].
-//     fn encoder(&self) -> Private<EncodeValueRef<'a, T>> {
-//         Private {
-//             tag_number: self.tag_number,
-//             tag_mode: self.tag_mode,
-//             value: EncodeValueRef(self.value),
-//         }
-//     }
-// }
-
-// impl<'a, T> EncodeValue for PrivateRef<'a, T>
-// where
-//     T: EncodeValue + Tagged,
-// {
-//     fn value_len(&self) -> Result<Length, Error> {
-//         self.encoder().value_len()
-//     }
-
-//     fn encode_value(&self, writer: &mut impl Writer) -> Result<(), Error> {
-//         self.encoder().encode_value(writer)
-//     }
-// }
-
-// impl<'a, T> Tagged for PrivateRef<'a, T>
-// where
-//     T: Tagged,
-// {
-//     fn tag(&self) -> Tag {
-//         self.encoder().tag()
-//     }
-// }
-
 #[cfg(test)]
 #[allow(clippy::unwrap_used)]
 mod tests {