From 13c7ffe1aa29efcd9a20ad75e858e46cd9b01b70 Mon Sep 17 00:00:00 2001
From: Nikolai Hartmann <nikoladze@posteo.de>
Date: Tue, 17 Sep 2024 12:58:02 +0200
Subject: [PATCH] flatten directory structure and add docstring for
 VectorVectorElementLink

---
 .../interpretation/known_forth/__init__.py    |  8 ++++++--
 .../{atlas/element_link.py => atlas.py}       | 19 ++++++++++++++++++-
 .../known_forth/atlas/__init__.py             |  5 -----
 3 files changed, 24 insertions(+), 8 deletions(-)
 rename src/uproot/interpretation/known_forth/{atlas/element_link.py => atlas.py} (72%)
 delete mode 100644 src/uproot/interpretation/known_forth/atlas/__init__.py

diff --git a/src/uproot/interpretation/known_forth/__init__.py b/src/uproot/interpretation/known_forth/__init__.py
index 35638b53b..0f0626e62 100644
--- a/src/uproot/interpretation/known_forth/__init__.py
+++ b/src/uproot/interpretation/known_forth/__init__.py
@@ -1,12 +1,16 @@
 # BSD 3-Clause License; see https://github.com/scikit-hep/uproot5/blob/main/LICENSE
 
 """
-This module defines known forth code for types it is known a priori.
+This module provides known forth code and awkward forms for types where it is known a priori.
+
+See :doc:`uproot.interpretation.known_forth.known_forth_of` for the function
+that provides the lookup of known forth codes and :doc:`uproot.interpretation.known_forth.atlas.VectorVectorElementLink` for an
+implementation used in ATLAS (D)AODs.
 """
 from __future__ import annotations
 
 import uproot
-from uproot.interpretation.known_forth.atlas.element_link import VectorVectorElementLink
+from uproot.interpretation.known_forth.atlas import VectorVectorElementLink
 
 KNOWN_FORTH_DICT = {
     "std::vector<std::vector<ElementLink<DataVector<xAOD::CaloCluster_v1>>>>": VectorVectorElementLink,
diff --git a/src/uproot/interpretation/known_forth/atlas/element_link.py b/src/uproot/interpretation/known_forth/atlas.py
similarity index 72%
rename from src/uproot/interpretation/known_forth/atlas/element_link.py
rename to src/uproot/interpretation/known_forth/atlas.py
index 04b766ba9..4db699748 100644
--- a/src/uproot/interpretation/known_forth/atlas/element_link.py
+++ b/src/uproot/interpretation/known_forth/atlas.py
@@ -1,7 +1,7 @@
 # BSD 3-Clause License; see https://github.com/scikit-hep/uproot5/blob/main/LICENSE
 
 """
-This module defines known forth code for some ElementLink data types in ATLAS (D)AODs
+This module defines ATLAS specific known forth code
 """
 
 from __future__ import annotations
@@ -10,6 +10,23 @@
 
 
 class VectorVectorElementLink:
+    """
+    Known forth and awkward form for ``std::vector<std::vector<ElementLink<T>>`` types in ATLAS (D)AODs
+
+    The forth code was adjusted from what was provided in
+    ``branch._complete_forth_code`` after running ``.array()`` once.
+
+    The binary data of one vector<vector<ElementLink<T>> looks as follows:
+
+    * 6 bytes header for the outer vector
+    * 4 bytes big endian uint for the size of the outer vector (node1)
+    * for each outer vector element:
+    * 4 bytes big endian uint for the size of the inner vector (node2)
+    * for each inner vector element:
+    * 20 bytes header for the ElementLink object
+    * 4 bytes big endian uint for the ``m_persKey`` member (node3)
+    * 4 bytes big endian uint for the ``m_persIndex`` member (node4)
+    """
 
     forth_code = """
 input stream
diff --git a/src/uproot/interpretation/known_forth/atlas/__init__.py b/src/uproot/interpretation/known_forth/atlas/__init__.py
deleted file mode 100644
index 22f85a5db..000000000
--- a/src/uproot/interpretation/known_forth/atlas/__init__.py
+++ /dev/null
@@ -1,5 +0,0 @@
-# BSD 3-Clause License; see https://github.com/scikit-hep/uproot5/blob/main/LICENSE
-
-"""
-This module defines ATLAS specific known forth code
-"""