From bba6fa5a11ec84b8a60ff05632e57a450fbb8915 Mon Sep 17 00:00:00 2001
From: Juri Leino <github@line-o.de>
Date: Wed, 26 Oct 2022 11:22:23 +0200
Subject: [PATCH] chore: add type hints to resources component

---
 components/resources.js | 42 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/components/resources.js b/components/resources.js
index 3a59753..c63d228 100644
--- a/components/resources.js
+++ b/components/resources.js
@@ -1,11 +1,53 @@
+/**
+ * @typedef { import("xmlrpc").Client } XMLRPCClient
+ */
+
+/**
+ * @typedef {Object} ResourceInfo
+ * @prop {string} name resource name or path
+ * @prop {"BinaryRerource"|"XMLResource"} type Resource type (XML or binary)
+ * @prop {string} owner DB user name
+ * @prop {string} group DB group name
+ * @prop {number} permissions as octet (e.g. 420)
+ * @prop {number} content-length length as 32-bit integer
+ * @prop {string} content-length-64bit length as BigInt string
+ * @prop {string} mime-type mimetype
+ * @prop {Date} created date the resource was created
+ * @prop {Date} modified date when the resource was last modified
+ * @prop {Array} acl Access Control List entries
+ */
+
+/**
+ * Gather information on a resource
+ * throws when resource does not exist, path points to a collection
+ *
+ * @param {XMLRPCClient} client RPC client instance
+ * @param {string} resourceIdentifier path to resource
+ * @returns {Promise<ResourceInfo>} Resource information
+ */
 function describe (client, resourceIdentifier) {
   return client.promisedMethodCall('describeResource', [resourceIdentifier])
 }
 
+/**
+ * Set the permissions for a resource or collection
+ *
+ * @param {XMLRPCClient} client RPC client instance
+ * @param {string} resourceIdentifier path to resource
+ * @param {number} permission octet number
+ * @returns {Promise<boolean>} true if the action was succesful
+ */
 function setPermissions (client, resourceIdentifier, permission) {
   return client.promisedMethodCall('setPermissions', [resourceIdentifier, permission])
 }
 
+/**
+ * Get the permissions for a resource or collection
+ *
+ * @param {XMLRPCClient} client RPC client instance
+ * @param {string} resourceIdentifier path to resource
+ * @returns {Promise<number>} permissions as octet number
+ */
 function getPermissions (client, resourceIdentifier) {
   return client.promisedMethodCall('getPermissions', [resourceIdentifier])
 }