flatten directory structure and add docstring for VectorVectorElementLink

Author: nikoladze

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,

…tation/known_forth/atlas/element_link.py …root/interpretation/known_forth/atlas.pysrc/uproot/interpretation/known_forth/atlas/element_link.py renamed to src/uproot/interpretation/known_forth/atlas.py src/uproot/interpretation/known_forth/atlas/element_link.py renamed to 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