Repository: alex/rust-asn1 (language: rust)

Issue:
Add copious docstrings
- [x] oid
- [x] bitstring
- [x] `parse`
- [x] `Parser::read_element`
- [x] `PrintableString`
- [x] `UTCTime`
- [x] `Choice1`, `Choice2`, `Choice3`
- [x] `Sequence`
- [x] `Implicit`
- [x] `Explicit`
- [x] module level


Discussion / hints:

Fix patch:
diff --git a/README.rst b/README.rst
index 1fcbf3f..123c1be 100644
--- a/README.rst
+++ b/README.rst
@@ -33,9 +33,9 @@ you would write:
 .. code-block:: rust
 
     let result = asn1::parse(data, |d| {
-        return d.parse::<asn1::Sequence>()?.parse(|d| {
-            let r = d.parse::<IntegerType>()?;
-            let s = d.parse::<IntegerType>()?;
+        return d.read_element::<asn1::Sequence>()?.parse(|d| {
+            let r = d.read_element::<IntegerType>()?;
+            let s = d.read_element::<IntegerType>()?;
             return Ok((r, s));
         })
     });
diff --git a/src/lib.rs b/src/lib.rs
index e261c4e..f532755 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -3,6 +3,39 @@
 #![cfg_attr(not(feature = "std"), no_std)]
 #![forbid(unsafe_code)]
 
+//! This crate provides you with the ability to parse ASN.1 encoded data. More precisely, it
+//! provides you with the ability to parse data encoded with ASN.1's DER (Distinguished Encoding
+//! Rules) encoding. It does not support BER (Basic Encoding Rules), CER (Canonical Encoding
+//! Rules), XER (XML Encoding Rules), CXER (Canonical XML Encoding Rules), or any other alphabet
+//! soup encodings -- and it never will.
+//!
+//! This crate does not, yet, provide the ability to generate ASN.1, only parse it.
+//!
+//! If you wanted to parse an ASN.1 structure like this:
+//! ```text
+//! Signature ::= SEQUENCE {
+//!     r INTEGER,
+//!     s INTEGER
+//! }
+//!
+//! Then you'd write the following code:
+//! ```
+//! use asn1;
+//! let result = asn1::parse(data, |d| {
+//!     return d.read_element::<asn1::Sequence>()?.parse(|d| {
+//!         let r = d.read_element::<u64>()?;
+//!         let s = d.read_element::<u64>()?;
+//!         return Ok((r, s));
+//!     })
+//! });
+//!
+//! In general everything about parsing is driven by providing different type parameters to
+//! `Parser.read_element`. Some types directly implement the `Asn1Element` trait, as seen with
+//! `u64` or `&[u8]` (`OCTET STRING`), while others use placeholder types which differ from the
+//! return type (`PrintableString` or `UtcTime`). There are also types such as `Implicit` and
+//! `Explicit` for handling tagged values, `Choice1`, `Choice2`, and `Choice3` available for
+//! choices, and `Option<T>` for handling `OPTIONAL` values.
+
 extern crate alloc;
 
 mod bit_string;
diff --git a/src/parser.rs b/src/parser.rs
index 2078163..f83cfed 100644
--- a/src/parser.rs
+++ b/src/parser.rs
@@ -261,6 +261,7 @@ macro_rules! impl_asn1_element_for_int {
 impl_asn1_element_for_int!(i8; true);
 impl_asn1_element_for_int!(u8; false);
 impl_asn1_element_for_int!(i64; true);
+impl_asn1_element_for_int!(u64; false);
 
 impl<'a> SimpleAsn1Element<'a> for ObjectIdentifier<'a> {
     const TAG: u8 = 0x06;
@@ -557,6 +558,21 @@ mod tests {
         ])
     }
 
+    #[test]
+    fn parse_int_u64() {
+        assert_parses::<u64>(&[
+            (
+                Ok(core::u64::MAX),
+                b"\x02\x09\x00\xff\xff\xff\xff\xff\xff\xff\xff",
+            ),
+            (Err(ParseError::InvalidValue), b"\x02\x01\xff"),
+            (
+                Err(ParseError::IntegerOverflow),
+                b"\x02\x09\x02\x00\x00\x00\x00\x00\x00\x00\x00",
+            ),
+        ]);
+    }
+
     #[test]
     fn test_parse_int_i8() {
         assert_parses::<i8>(&[


Test patch: