[#777,!464] Template updated

diff --git a/doc/sphinx/api/_template.json b/doc/sphinx/api/_template.json
index c0cd378687454b23f95298af36de97eb3ab7eb6a..a0183e13e1af84b47ee591ef2471a0f206756bce 100644 (file)
--- a/doc/sphinx/api/_template.json
+++ b/doc/sphinx/api/_template.json
@@ -1,14 +1,19 @@
+// Note the api/*.json files are to be processed by api2doc.py and possibly other
+// JSON tools that do not handle comments. If using this template, make sure you
+// have all the comments removed.
 {
     // This specifies the name of the command. Must be the same as the filename.
     "name": "template-command",
 
-    // This provides a short description.
-    "brief": "a sentence or two explaining what it is",
+    // This provides a short description. Since JSON does not support multi-line
+    // strings, each line is a separate string. Feel free to have one long string,
+    // or several lines of nicely wrapped text.
+    "brief": [ "a sentence or two explaining what it is" ],
 
     // This provides a full description. Since we have most (all?) commands
     // already documented, we don't want to copy over the text. Instead,
     // we provide links to specific section.
-    "description": "See <xref linkend=\"anchor-in-the-docs\"/>",
+    "description": "See :ref:`anchor-in-the-docs`/>",
 
     // This enumerates the daemons that are able to handle specific commands.
     // Usually this will be a subset of those specified below as there are very
@@ -23,18 +28,17 @@
     // Many commands are provided by a hook. Specify the name of the hook here.
     // If this hook is provided by the daemons natively (without needing to load
     // a hook), remove the whole "hook" entry.
-    "hook": "name of the hook that provides this command. remove if provided by
-             the core code",
+    "hook": "name of the hook that provides this command. remove if provided by the core code",
 
     // This defines the syntax of the command.
-    "cmd-syntax": "Syntax of the command",
+    "cmd-syntax": [ "Syntax of the command" ],
 
     // This defines a description printed immediately below the command syntax.
-    "cmd-comment": "Possibly some extra comments after the syntax.",
+    "cmd-comment": [ "Possibly some extra comments after the syntax." ],
 
     // This defines the syntax of the response.
-    "resp-syntax": "Syntax of the response",
+    "resp-syntax": [ "Syntax of the response" ],
 
     // This defines a description printed immediately below the response syntax.
-    "resp-comment": "Optional extra comments after the response syntax."
+    "resp-comment": [ "Optional extra comments after the response syntax." ]
 }