der: add doc examples for Tag, Length and Header (#2051)

Author: dishmaker

der/src/header.rs

@@ -7,6 +7,27 @@ use crate::{Decode, DerOrd, Encode, Error, ErrorKind, Length, Reader, Result, Ta
 use core::cmp::Ordering;
 
 /// ASN.1 DER headers: tag + length component of TLV-encoded values
+///
+///
+/// ## Examples
+/// ```
+/// use der::{Decode, Header, Length, Reader, SliceReader, Tag};
+///
+/// let mut reader = SliceReader::new(&[0x04, 0x02, 0x31, 0x32]).unwrap();
+/// let header = Header::decode(&mut reader).expect("valid header");
+///
+/// assert_eq!(header, Header::new(Tag::OctetString, Length::new(2)));
+///
+/// assert_eq!(reader.read_slice(2u8.into()).unwrap(), b"12");
+/// ```
+///
+/// ```
+/// use der::{Encode, Header, Length, Tag};
+/// let header = Header::new(Tag::Sequence, Length::new(256));
+///
+/// // Header of 256-byte SEQUENCE is 4-byte long
+/// assert_eq!(header.encoded_len(), Ok(Length::new(4)));
+/// ```
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct Header {
     /// Tag representing the type of the encoded value

der/src/length.rs

@@ -18,6 +18,33 @@ use core::{
 };
 
 /// ASN.1-encoded length.
+///
+/// ## Examples
+/// ```
+/// use der::{Decode, Length, SliceReader};
+///
+/// let mut reader = SliceReader::new(&[0x82, 0xAA, 0xBB]).unwrap();
+/// let length = Length::decode(&mut reader).expect("valid length");
+///
+/// assert_eq!(length, Length::new(0xAABB));
+/// ```
+///
+/// 5-byte lengths are supported:
+/// ```
+/// use der::{Encode, Length};
+/// let length = Length::new(0x10000000);
+///
+/// assert_eq!(length.encoded_len(), Ok(Length::new(5)));
+/// ```
+///
+/// Invalid lengths produce an error:
+/// ```
+/// use der::{Decode, Length, SliceReader};
+///
+/// let mut reader = SliceReader::new(&[0x81, 0x7F]).unwrap();
+///
+/// Length::decode(&mut reader).expect_err("non-canonical length should be rejected");
+/// ```
 #[derive(Copy, Clone, Default, Eq, Hash, PartialEq, PartialOrd, Ord)]
 pub struct Length {
     /// Inner length as a `u32`. Note that the decoder and encoder also support a maximum length

der/src/tag.rs

@@ -62,6 +62,34 @@ impl<T: FixedTag + ?Sized> IsConstructed for T {
 /// - Bits 8/7: [`Class`]
 /// - Bit 6: primitive (0) or constructed (1)
 /// - Bits 5-1: tag number
+///
+/// ## Examples
+/// ```
+/// use der::{Decode, Tag, SliceReader};
+///
+/// let mut reader = SliceReader::new(&[0x30]).unwrap();
+/// let tag = Tag::decode(&mut reader).expect("valid tag");
+///
+/// assert_eq!(tag, Tag::Sequence);
+/// ```
+///
+/// Invalid tags produce an error:
+/// ```
+/// use der::{Decode, Tag};
+///
+/// // 0x21 is an invalid CONSTRUCTED BOOLEAN
+/// Tag::from_der(&[0x21]).expect_err("invalid tag");
+/// ```
+///
+/// `APPLICATION`, `CONTEXT-SPECIFIC` and `PRIVATE` tags are supported:
+/// ```
+/// use der::{Decode, Tag, TagNumber};
+///
+/// // `APPLICATION [33] (constructed)`
+/// let tag = Tag::from_der(&[0x7F, 0x21]).expect("valid tag");
+///
+/// assert_eq!(tag, Tag::Application { constructed: true, number: TagNumber(33) });
+/// ```
 #[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
 #[derive(Copy, Clone, Eq, Hash, PartialEq, PartialOrd, Ord)]
 #[non_exhaustive]