enhance: improve documentation for /users/ endpoints (#8790)

* docs: category & description for reset password

* docs: category & description for testing

* docs: descriptions for groups endpoints

* docs: descriptions for drive file endpoints

* docs: descriptions for sw endpoints

* docs: descriptions for user list endpoints

* docs: descriptions & result type for gallery posts

* docs: descriptions & result type for user endpoints

* docs: add return type for stats

packages/backend/src/server/api/endpoints/users/groups/create.ts

@@ -11,6 +11,8 @@ export const meta = {
 
 	kind: 'write:user-groups',
 
+	description: 'Create a new group.',
+
 	res: {
 		type: 'object',
 		optional: false, nullable: false,

packages/backend/src/server/api/endpoints/users/groups/delete.ts

@@ -9,6 +9,8 @@ export const meta = {
 
 	kind: 'write:user-groups',
 
+	description: 'Delete an existing group.',
+
 	errors: {
 		noSuchGroup: {
 			message: 'No such group.',

packages/backend/src/server/api/endpoints/users/groups/invitations/accept.ts

@@ -11,6 +11,8 @@ export const meta = {
 
 	kind: 'write:user-groups',
 
+	description: 'Join a group the authenticated user has been invited to.',
+
 	errors: {
 		noSuchInvitation: {
 			message: 'No such invitation.',

packages/backend/src/server/api/endpoints/users/groups/invitations/reject.ts

@@ -9,6 +9,8 @@ export const meta = {
 
 	kind: 'write:user-groups',
 
+	description: 'Delete an existing group invitation for the authenticated user without joining the group.',
+
 	errors: {
 		noSuchInvitation: {
 			message: 'No such invitation.',

packages/backend/src/server/api/endpoints/users/groups/invite.ts

@@ -13,6 +13,8 @@ export const meta = {
 
 	kind: 'write:user-groups',
 
+	description: 'Invite a user to an existing group.',
+
 	errors: {
 		noSuchGroup: {
 			message: 'No such group.',

packages/backend/src/server/api/endpoints/users/groups/joined.ts

@@ -9,6 +9,8 @@ export const meta = {
 
 	kind: 'read:user-groups',
 
+	description: 'List the groups that the authenticated user is a member of.',
+
 	res: {
 		type: 'array',
 		optional: false, nullable: false,

packages/backend/src/server/api/endpoints/users/groups/leave.ts

@@ -9,6 +9,8 @@ export const meta = {
 
 	kind: 'write:user-groups',
 
+	description: 'Leave a group. The owner of a group can not leave. They must transfer ownership or delete the group instead.',
+
 	errors: {
 		noSuchGroup: {
 			message: 'No such group.',

packages/backend/src/server/api/endpoints/users/groups/owned.ts

@@ -8,6 +8,8 @@ export const meta = {
 
 	kind: 'read:user-groups',
 
+	description: 'List the groups that the authenticated user is the owner of.',
+
 	res: {
 		type: 'array',
 		optional: false, nullable: false,

packages/backend/src/server/api/endpoints/users/groups/pull.ts

@@ -10,6 +10,8 @@ export const meta = {
 
 	kind: 'write:user-groups',
 
+	description: 'Removes a specified user from a group. The owner can not be removed.',
+
 	errors: {
 		noSuchGroup: {
 			message: 'No such group.',

packages/backend/src/server/api/endpoints/users/groups/show.ts

@@ -9,6 +9,8 @@ export const meta = {
 
 	kind: 'read:user-groups',
 
+	description: 'Show the properties of a group.',
+
 	res: {
 		type: 'object',
 		optional: false, nullable: false,

packages/backend/src/server/api/endpoints/users/groups/transfer.ts

@@ -10,6 +10,8 @@ export const meta = {
 
 	kind: 'write:user-groups',
 
+	description: 'Transfer ownership of a group from the authenticated user to another user.',
+
 	res: {
 		type: 'object',
 		optional: false, nullable: false,

packages/backend/src/server/api/endpoints/users/groups/update.ts

@@ -9,6 +9,8 @@ export const meta = {
 
 	kind: 'write:user-groups',
 
+	description: 'Update the properties of a group.',
+
 	res: {
 		type: 'object',
 		optional: false, nullable: false,