doveadm: Rework response documentation

The old 'fields' entry in data/doveadm.js has been replaced with the
'response' entry.

This new entry allows for text description and data type output.

Output example JSON server response in the HTTP API block.

Author: slusarz

components/DoveadmComponent.vue

@@ -49,7 +49,7 @@ function httpClick(k) {
     <a class="header-anchor" :href="'#' + k"></a>
    </h3>
 
-   <table v-if="v.man_link || v.fields || v.added || v.changed || v.deprecated || v.removed">
+   <table v-if="v.man_link || v.response || v.added || v.changed || v.deprecated || v.removed">
     <tbody>
      <tr v-if="v.man_link">
       <th style="text-align: right;">Man Page</th>
@@ -80,20 +80,22 @@ function httpClick(k) {
       </td>
     </tr>
 
-     <tr v-if="v.fields">
-      <th style="text-align: right;">Return Values</th>
+     <tr v-if="v.response">
+      <th style="text-align: right;">Response Values</th>
       <td>
        <table>
         <thead>
          <tr>
           <th>Key</th>
-          <th>Value</th>
+          <th>Type</th>
+          <th>Description</th>
          </tr>
         </thead>
         <tbody>
-         <tr v-for="elem in v.fields">
+         <tr v-for="elem in v.response">
           <td><code>{{ elem.key }}</code></td>
-          <td v-html="elem.value" />
+          <td v-html="elem.type" />
+          <td v-html="elem.text" />
          </tr>
         </tbody>
        </table>

components/DoveadmHttpApiComponent.vue

@@ -20,6 +20,22 @@ const jsonReq =
 		"tag1"
 	]
 ]
+
+const resp = {}
+if (d.response) {
+	for (let elem of d.response) {
+		resp[elem.key] = elem.example
+	}
+}
+
+const jsonResp =
+[
+	[
+		"doveadmResponse",
+		[ resp ],
+		"tag1"
+	]
+]
 </script>
 
 <template>
@@ -88,5 +104,15 @@ const jsonReq =
    <span class="lang"></span>
    <pre><code>wget --header="Content-Type: application/json" --user=doveadm --password=password --auth-no-challenge --post-data='{{ JSON.stringify(jsonReq) }}' --output-document - http://example.com:8080/doveadm/v1</code></pre>
   </div>
+
+  <template v-if="d.response?.length">
+   <p class="custom-block-title">Example Server Response</p>
+
+   <div class="language- vp-adaptive-theme">
+    <button class="copy" title="Copy" />
+    <span class="lang"></span>
+     <pre><code>{{ JSON.stringify(jsonResp, null, 4) }}</code></pre>
+   </div>
+  </template>
  </div>
 </template>

data/doveadm.js

@@ -2,7 +2,8 @@
 import { doveadm_arg_types,
 		 doveadm_args_query,
 		 doveadm_args_usermask,
-		 doveadm_flag_types } from '../lib/doveadm.js'
+		 doveadm_flag_types,
+		 doveadm_response_types } from '../lib/doveadm.js'
 
 export const doveadm = {
 
@@ -51,8 +52,21 @@ export const doveadm = {
 		// deprecated: {},
 		// removed: {},
 
-		// Fields/Values returned. Values are rendered w/Markdown.
-		// fields: {},
+		// Response data.
+		// KEY = identifier
+		// response: {
+		//     key: {
+		//         // An example value to be used in documentation.
+		//         example: 0,
+		//
+		//         // The description of the response data type.
+		//         // Rendered w/Markdown.
+		//         text: `Description`,
+		//
+		//         // The response data type
+		//         type: doveadm_response_types.INTEGER,
+		//     }
+		// },
 
 		// What doveadm flags does this command support (bit field)
 		// Arguments are automatically added for each flag set
@@ -237,8 +251,11 @@ Applicable to [[link,mdbox]] and [[link,sdbox]] mailbox formats only.
 				text: `UID of user to apply operation to.`,
 			},
 		},
-		fields: {
-			'entries': 0
+		response: {
+			entries: {
+				type: doveadm_response_types.INTEGER,
+				text: `The number of cache entries flushed.`
+			},
 		},
 		man: 'doveadm-auth',
 		text: `Flush authentication cache.`,
@@ -1355,7 +1372,7 @@ to secure it.
 				text: `Mailbox mask.`
 			},
 		},
-		fields: {},
+		response: {},
 		flags: doveadm_flag_types.USER,
 		plugin: 'mail-crypt',
 		man: 'doveadm-mailbox-cryptokey',
@@ -1375,7 +1392,7 @@ to secure it.
 				text: `Mailbox mask.`
 			},
 		},
-		fields: {},
+		response: {},
 		flags: doveadm_flag_types.USER,
 		plugin: 'mail-crypt',
 		man: 'doveadm-mailbox-cryptokey',
@@ -1410,7 +1427,7 @@ to secure it.
 				text: `Old password.`
 			},
 		},
-		fields: {},
+		response: {},
 		flags: doveadm_flag_types.USER,
 		plugin: 'mail-crypt',
 		man: 'doveadm-mailbox-cryptokey',

lib/data/doveadm.data.js

@@ -1,4 +1,4 @@
-import { doveadm_arg_types, doveadm_flag_types, getDoveadmCmdLine } from '../doveadm.js'
+import { doveadm_arg_types, doveadm_flag_types, doveadm_response_types, getDoveadmCmdLine } from '../doveadm.js'
 import { getVitepressMd } from '../markdown.js'
 import { addWatchPaths, loadData, normalizeArrayData } from '../utility.js'
 import camelCase from 'camelcase'
@@ -39,17 +39,26 @@ const doveadm_userfileargs = {
 function typeToString(type) {
 	switch (type) {
 	case doveadm_arg_types.ARRAY:
-		return 'array';
+		return 'array'
 	case doveadm_arg_types.BOOL:
-		return 'boolean';
+		return 'boolean'
 	case doveadm_arg_types.INTEGER:
-		return 'integer';
+		return 'integer'
 	case doveadm_arg_types.STRING:
-		return 'string';
+		return 'string'
 	case doveadm_arg_types.SEARCH_QUERY:
-		return 'search_query';
+		return 'search_query'
 	case doveadm_arg_types.ISTREAM:
-		return 'istream';
+		return 'istream'
+	}
+}
+
+function responseTypeLookup(type) {
+	switch (type) {
+	case doveadm_response_types.INTEGER:
+		return [ 'integer', 1 ]
+	case doveadm_response_types.STRING:
+		return [ 'string', 'example' ]
 	}
 }
 
@@ -97,19 +106,22 @@ async function normalizeDoveadm(doveadm) {
 			}
 		}
 
-		/* Return values. */
-		if (v.fields) {
-			const fields = []
-			for (const [k2, v2] of Object.entries(v.fields)) {
-				fields.push({
+		/* Response values. */
+		if (v.response) {
+			const response = []
+			for (const [k2, v2] of Object.entries(v.response)) {
+				var rtl = responseTypeLookup(v2.type)
+				response.push({
+					example: v2.example ?? rtl[1],
 					key: k2,
-					value: v2 ? md.renderInline(String(v2)) : null
+					type: rtl[0],
+					text: v2.text ? md.renderInline(String(v2.text)) : null
 				})
 			}
-			v.fields = fields
+			v.response = response
 		}
-		if (!v.fields || !v.fields.length) {
-			delete v['fields']
+		if (!v.response || !v.response.length) {
+			delete v['response']
 		}
 
 		/* Text Description. */

lib/doveadm.js

@@ -16,6 +16,12 @@ export const doveadm_flag_types = {
 	USERMASK:		4,
 }
 
+/* List of Doveadm response value types. */
+export const doveadm_response_types = {
+	INTEGER:	1,
+	STRING:		2,
+}
+
 export const doveadm_args_query = {
 	//example: ['mailbox', 'INBOX/myfoldertoo', 'savedbefore', 'since', '30d'],
 	positional: true,