Merge 9c6ee06 into 6a5b642

tuf/api/metadata.py

@@ -3,9 +3,35 @@
 
 """TUF role metadata model.
 
-This module provides container classes for TUF role metadata, including methods
-to read and write from and to file, perform TUF-compliant metadata updates, and
-create and verify signatures.
+This module contains low-level API through container classes for TUF role
+metadata. The API aims to provide:
+- Safe de/serialization of metadata to and from files
+- Access to and modification of signed metadata content
+- Signing metadata and verifying signatures
+
+Each of the top level metadata roles is an instance of the Metadata[T] class
+where the "signed" portion of each of the roles (or the "T") is an instance
+of one of the classes:
+- `Root
+<https://theupdateframework.readthedocs.io/en/latest/api/tuf.api.metadata.html#tuf.api.metadata.Root>`_
+- `Timestamp
+<https://theupdateframework.readthedocs.io/en/latest/api/tuf.api.metadata.html#tuf.api.metadata.Timestamp>`_
+- `Snapshot
+<https://theupdateframework.readthedocs.io/en/latest/api/tuf.api.metadata.html#tuf.api.metadata.Snapshot>`_
+- `Targets
+<https://theupdateframework.readthedocs.io/en/latest/api/tuf.api.metadata.html#tuf.api.metadata.Targets>`_.
+For example, Metadata[Root] represents the TUF root role and that in practice
+means that this is a Metadata object with a signed attribute of type Root.
+
+Additionally, there are helper classes providing abstractions over the complex
+metadata fields inside the four top level classes - Root, Timestamp, Snapshot
+and Targets.
+
+Note: the metadata module provides a low-level API and as such it doesn't use
+concepts like "repository" or "trusted collection of metadata".
+In this file there is no implementation of the repository-side logic or client
+update workflows, but instead it provides solid base for other components to do
+so.
 
 The metadata model supports any custom serialization format, defaulting to JSON
 as wireline format and Canonical JSON for reproducible signature creation and