diff --git a/swh/storage/storage.py b/swh/storage/storage.py
--- a/swh/storage/storage.py
+++ b/swh/storage/storage.py
@@ -1289,11 +1289,30 @@
     @db_transaction()
     def metadata_provider_add(self, provider_name, provider_type, provider_url,
                               metadata, db=None, cur=None):
+        """Add a metadata provider.
+
+        Args:
+            provider_name (str): Its name
+            provider_type (str): Its type (eg. `'deposit-client'`)
+            provider_url (str): Its URL
+            metadata: JSON-encodable object
+
+        Returns:
+            dict: same as args, plus an 'id' key.
+        """
         return db.metadata_provider_add(provider_name, provider_type,
                                         provider_url, metadata, cur)
 
     @db_transaction()
     def metadata_provider_get(self, provider_id, db=None, cur=None):
+        """Get a metadata provider
+
+        Args:
+            provider_id: Its identifier, as given by `metadata_provider_add`.
+
+        Returns:
+            dict: same as `metadata_provider_add`.
+        """
         result = db.metadata_provider_get(provider_id)
         if not result:
             return None
@@ -1301,6 +1320,16 @@
 
     @db_transaction()
     def metadata_provider_get_by(self, provider, db=None, cur=None):
+        """Get a metadata provider
+
+        Args:
+            provider (dict): A dictionary with keys:
+                * provider_name: Its name
+                * provider_url: Its URL
+
+        Returns:
+            dict: same as `metadata_provider_add`.
+        """
         result = db.metadata_provider_get_by(provider['provider_name'],
                                              provider['provider_url'])
         if not result: