From c5cc758eb979e793fda8918897451c60067ef526 Mon Sep 17 00:00:00 2001
From: GiggleLiu <cacate0129@gmail.com>
Date: Wed, 9 Sep 2026 01:00:15 +0800
Subject: [PATCH] Document LongLongUInt representation and arithmetic

---
 README.md           |  1 +
 src/longlonguint.jl | 28 +++++++++++++++++++++++++---
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 9a3ee24..5f8ed64 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,7 @@
 [![Build Status](https://github.com/QuantumBFS/BitBasis.jl/workflows/CI/badge.svg)](https://github.com/QuantumBFS/BitBasis.jl/actions)
 [![Codecov](https://codecov.io/gh/QuantumBFS/BitBasis.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/QuantumBFS/BitBasis.jl)
 [![Aqua QA](https://img.shields.io/badge/Aqua.jl-%F0%9F%8C%A2-aqua.svg)](https://github.com/JuliaTesting/Aqua.jl)
+![Agent maintained](https://img.shields.io/badge/maintenance-agent%20maintained-blue)
 
 
 Types and operations for basis represented by bits in linear algebra.
diff --git a/src/longlonguint.jl b/src/longlonguint.jl
index ad19b2f..cd7021a 100644
--- a/src/longlonguint.jl
+++ b/src/longlonguint.jl
@@ -1,7 +1,29 @@
 """
-    LongLongUInt{C} <: Integer
+    LongLongUInt{C} <: Unsigned
 
-A `LongLongUInt{C}` is an integer with `C` `UInt` numbers to store the value.
+A fixed-width unsigned integer stored in `C` machine-word-sized `UInt` values.
+The first element of `content` is the most significant word and the last is the
+least significant word, so the width is `C * sizeof(UInt) * 8` bits. Arithmetic
+is fixed-width and discards overflow beyond that width.
+
+Construct a value from a tuple of words or convert an integer to an explicitly
+sized value. `LongLongUInt` supports comparisons, bitwise operations, shifts,
+addition, subtraction, multiplication, division, and conversion to `BigInt`.
+
+# Examples
+
+```jldoctest
+julia> x = LongLongUInt((0x0000000000000001, 0x0000000000000002));
+
+julia> BigInt(x) == (big(1) << 64) + 2
+true
+
+julia> x >> 64 == LongLongUInt((0x0000000000000000, 0x0000000000000001))
+true
+
+julia> typemax(UInt) * LongLongUInt{1}(2) == LongLongUInt{1}(typemax(UInt) - 1)
+true
+```
 """
 struct LongLongUInt{C} <: Unsigned
     content::NTuple{C, UInt}
@@ -234,4 +256,4 @@ function Base.hash(bits_tuple::Tuple{LongLongUInt{C}, Vararg{LongLongUInt{C}, M}
         hash0 = Base.hash(bits_tuple[i].content, hash0)
     end
     return hash0
-end
\ No newline at end of file
+end