diff --git a/package_manager/package_manager.api.php b/package_manager/package_manager.api.php
index 8119419cb285de75ffb54705e9df67acbd300182..3b565fec8cdaefd9041cb3a2367dc27675897ea6 100644
--- a/package_manager/package_manager.api.php
+++ b/package_manager/package_manager.api.php
@@ -275,5 +275,15 @@
  *   Composer at the command line and get information from it about the
  *   project's `composer.json`, which packages are installed, etc.
  *
+ * @section sec_package_manager_failure_marker Package Manager failure marker
+ * A file PACKAGE_MANAGER_FAILURE.yml is placed in the active directory while
+ * staged code is copied back into it, and then removed after the copying is
+ * finished. If this file exists, it means that the staged changes failed to be
+ * applied to the active directory (for example: a file system error, or the
+ * copying process was interrupted), and the site is therefore in an
+ * indeterminate state. The only thing you can do is to restore the code and
+ * database from a backup.
+ * @see \Drupal\package_manager\FailureMarker
+ *
  * @}
  */