treewide: add usage help to various iocsh functions

modules/ca/src/client/acctstRegister.cpp

@@ -32,7 +32,13 @@ static const iocshArg    *acctstArgs[] =
     &acctstArg3,
     &acctstArg4
 };
-static const iocshFuncDef acctstFuncDef = {"acctst", 5, acctstArgs};
+static const iocshFuncDef acctstFuncDef = {
+    "acctst",
+    5,
+    acctstArgs,
+    "Execute a Channel Access regression test.\n\n"
+    "For more information, see the 'acctst' documentation in the Channel Access reference.\n",
+};
 
 
 /* Wrapper called by iocsh, selects the argument types that print needs */

modules/database/src/ioc/db/dbIocRegister.c

@@ -35,8 +35,14 @@ static const iocshArg * const dbLoadDatabaseArgs[3] =
 {
     &dbLoadDatabaseArg0,&dbLoadDatabaseArg1,&dbLoadDatabaseArg2
 };
-static const iocshFuncDef dbLoadDatabaseFuncDef =
-    {"dbLoadDatabase",3,dbLoadDatabaseArgs};
+static const iocshFuncDef dbLoadDatabaseFuncDef = {
+    "dbLoadDatabase",
+    3,
+    dbLoadDatabaseArgs,
+    "Load the given .dbd file, with 'path' added as a search path, with the given substitutions.\n\n"
+    "Substitutions are usually not needed for .dbd files.\n\n"
+    "Example: dbLoadDatabase dbd/my.dbd\n",
+};
 static void dbLoadDatabaseCallFunc(const iocshArgBuf *args)
 {
     iocshSetError(dbLoadDatabase(args[0].sval,args[1].sval,args[2].sval));
@@ -46,7 +52,14 @@ static void dbLoadDatabaseCallFunc(const iocshArgBuf *args)
 static const iocshArg dbLoadRecordsArg0 = { "file name",iocshArgString};
 static const iocshArg dbLoadRecordsArg1 = { "substitutions",iocshArgString};
 static const iocshArg * const dbLoadRecordsArgs[2] = {&dbLoadRecordsArg0,&dbLoadRecordsArg1};
-static const iocshFuncDef dbLoadRecordsFuncDef = {"dbLoadRecords",2,dbLoadRecordsArgs};
+static const iocshFuncDef dbLoadRecordsFuncDef = {
+    "dbLoadRecords",
+    2,
+    dbLoadRecordsArgs,
+    "Load the given .db file, with the given substitutions.\n\n"
+    "Substitutions should be given in the format 'var1=value1,var2=value2'.\n\n"
+    "Example: dbLoadRecords db/myRecords.db 'user=myself,host=myhost'\n",
+};
 static void dbLoadRecordsCallFunc(const iocshArgBuf *args)
 {
     iocshSetError(dbLoadRecords(args[0].sval,args[1].sval));

modules/database/src/ioc/dbStatic/dbStaticIocRegister.c

@@ -106,7 +106,13 @@ static void dbDumpDriverCallFunc(const iocshArgBuf *args)
 
 /* dbDumpLink */
 static const iocshArg * const dbDumpLinkArgs[] = { &argPdbbase};
-static const iocshFuncDef dbDumpLinkFuncDef = {"dbDumpLink",1,dbDumpLinkArgs};
+static const iocshFuncDef dbDumpLinkFuncDef = {
+    "dbDumpLink",
+    1,
+    dbDumpLinkArgs,
+    "Dump list of registered links\n"
+    "Example: dbDumpLink pdbbase\n",
+};
 static void dbDumpLinkCallFunc(const iocshArgBuf *args)
 {
     dbDumpLink(*iocshPpdbbase);
@@ -147,7 +153,13 @@ static void dbDumpVariableCallFunc(const iocshArgBuf *args)
 static const iocshArg dbDumpBreaktableArg1 = { "tableName",iocshArgString};
 static const iocshArg * const dbDumpBreaktableArgs[] =
     {&argPdbbase,&dbDumpBreaktableArg1};
-static const iocshFuncDef dbDumpBreaktableFuncDef = {"dbDumpBreaktable",2,dbDumpBreaktableArgs};
+static const iocshFuncDef dbDumpBreaktableFuncDef = {
+    "dbDumpBreaktable",
+    2,
+    dbDumpBreaktableArgs,
+    "Dump the given break table\n"
+    "Example: dbDumpBreaktable pdbbase typeKdegC\n",
+};
 static void dbDumpBreaktableCallFunc(const iocshArgBuf *args)
 {
     dbDumpBreaktable(*iocshPpdbbase,args[1].sval);
@@ -157,7 +169,14 @@ static void dbDumpBreaktableCallFunc(const iocshArgBuf *args)
 static const iocshArg dbPvdDumpArg1 = { "verbose",iocshArgInt};
 static const iocshArg * const dbPvdDumpArgs[] = {
     &argPdbbase,&dbPvdDumpArg1};
-static const iocshFuncDef dbPvdDumpFuncDef = {"dbPvdDump",2,dbPvdDumpArgs};
+static const iocshFuncDef dbPvdDumpFuncDef = {
+    "dbPvdDump",
+    2,
+    dbPvdDumpArgs,
+    "Dump the various buckets of the process variable directory.\n"
+    "If verbose is greater than 0, also print the process variables in each bucket.\n"
+    "Example: dbPvdDump pdbbase 1\n",
+};
 static void dbPvdDumpCallFunc(const iocshArgBuf *args)
 {
     dbPvdDump(*iocshPpdbbase,args[1].ival);
@@ -167,7 +186,16 @@ static void dbPvdDumpCallFunc(const iocshArgBuf *args)
 static const iocshArg dbPvdTableSizeArg0 = { "size",iocshArgInt};
 static const iocshArg * const dbPvdTableSizeArgs[1] =
     {&dbPvdTableSizeArg0};
-static const iocshFuncDef dbPvdTableSizeFuncDef = {"dbPvdTableSize",1,dbPvdTableSizeArgs};
+static const iocshFuncDef dbPvdTableSizeFuncDef = {
+    "dbPvdTableSize",
+    1,
+    dbPvdTableSizeArgs,
+    "Change the number of buckets in the process variable directory.\n\n"
+    "The process variable directory size should be set before loading the database.\n"
+    "The size of the process variable directory can automatically grow.\n"
+    "The size must be a power of 2.\n\n"
+    "Example: dbPvdTableSize 1024\n",
+};
 static void dbPvdTableSizeCallFunc(const iocshArgBuf *args)
 {
     dbPvdTableSize(args[0].ival);
@@ -175,7 +203,15 @@ static void dbPvdTableSizeCallFunc(const iocshArgBuf *args)
 
 /* dbReportDeviceConfig */
 static const iocshArg * const dbReportDeviceConfigArgs[] = {&argPdbbase};
-static const iocshFuncDef dbReportDeviceConfigFuncDef = {"dbReportDeviceConfig",1,dbReportDeviceConfigArgs};
+static const iocshFuncDef dbReportDeviceConfigFuncDef = {
+    "dbReportDeviceConfig",
+    1,
+    dbReportDeviceConfigArgs,
+    "Print the link type, link value, device type, record name,\n"
+    "and linearisation info (if applicable),\n"
+    "for every record using a specific device type.\n\n"
+    "Example: dbReportDeviceConfig pdbbase\n",
+};
 static void dbReportDeviceConfigCallFunc(const iocshArgBuf *args)
 {
     dbReportDeviceConfig(*iocshPpdbbase,stdout);

modules/database/src/ioc/dbtemplate/dbtoolsIocRegister.c

@@ -14,12 +14,21 @@
 
 /* dbLoadTemplate */
 static const iocshArg dbLoadTemplateArg0 = {"filename", iocshArgString};
-static const iocshArg dbLoadTemplateArg1 = {"var=value", iocshArgString};
+static const iocshArg dbLoadTemplateArg1 = {"var1=value1,var2=value2", iocshArgString};
 static const iocshArg * const dbLoadTemplateArgs[2] = {
     &dbLoadTemplateArg0, &dbLoadTemplateArg1
 };
-static const iocshFuncDef dbLoadTemplateFuncDef =
-    {"dbLoadTemplate", 2, dbLoadTemplateArgs};
+static const iocshFuncDef dbLoadTemplateFuncDef = {
+    "dbLoadTemplate",
+    2,
+    dbLoadTemplateArgs,
+    "Load the substitution file given as first argument, apply the substitutions\n"
+    "for each template in the substitution file, and load them using 'dbLoadRecords'.\n\n"
+    "The second argument provides extra variables to substitute in the\n"
+    "template files (not the substitution file).\n\n"
+    "See 'help dbLoadRecords' for more information.\n\n"
+    "Example: dbLoadTemplate db/my.substitutions 'user=myself,host=myhost'\n",
+};
 static void dbLoadTemplateCallFunc(const iocshArgBuf *args)
 {
     iocshSetError(dbLoadTemplate(args[0].sval, args[1].sval));

modules/database/src/ioc/misc/dlload.c

@@ -19,7 +19,13 @@ IOCSH_STATIC_FUNC void dlload(const char* name)
 
 static const iocshArg dlloadArg0 = { "path/library.so", iocshArgString};
 static const iocshArg * const dlloadArgs[] = {&dlloadArg0};
-static const iocshFuncDef dlloadFuncDef = {"dlload", 1, dlloadArgs};
+static const iocshFuncDef dlloadFuncDef = {
+    "dlload",
+    1,
+    dlloadArgs,
+    "Load the given shared library.\n\n"
+    "Example: dlload myLibrary.so\n",
+};
 static void dlloadCallFunc(const iocshArgBuf *args)
 {
     dlload(args[0].sval);

modules/database/src/ioc/misc/iocshRegisterCommon.c

@@ -28,8 +28,19 @@
 /* registerAllRecordDeviceDrivers */
 static const iocshArg rrddArg0 = {"pdbbase", iocshArgPdbbase};
 static const iocshArg *rrddArgs[] = {&rrddArg0};
-static const iocshFuncDef rrddFuncDef =
-    {"registerAllRecordDeviceDrivers", 1, rrddArgs};
+static const iocshFuncDef rrddFuncDef = {
+    "registerAllRecordDeviceDrivers",
+    1,
+    rrddArgs,
+    "Register all records, devices, from all DBD available.\n\n"
+    "Calling this function is equivalent to calling every\n"
+    "'<name>_registerRecordDeviceDriver' which has been linked\n"
+    "into the process, e.g. by dynamic loading, or by linking with\n"
+    "a generated '<name>_registerRecordDeviceDriver.cpp' files.\n\n"
+    "These are registered into the database given as first argument,\n"
+    "which should always be 'pdbbase'.\n\n"
+    "Example: registerAllRecordDeviceDrivers pdbbase\n",
+};
 static void rrddCallFunc(const iocshArgBuf *args)
 {
     iocshSetError(registerAllRecordDeviceDrivers(*iocshPpdbbase));

modules/database/src/ioc/registry/registryIocRegister.c

@@ -21,28 +21,48 @@ static const iocshArg * const registryXxxFindArgs[1] = {&registryXxxFindArg0};
 
 /* registryRecordTypeFind */
 static const iocshFuncDef registryRecordTypeFindFuncDef = {
-    "registryRecordTypeFind",1,registryXxxFindArgs};
+    "registryRecordTypeFind",
+    1,
+    registryXxxFindArgs,
+    "Prints the registry address of the record type given as first argument.\n\n"
+    "Example: registryRecordTypeFind ai\n",
+};
 static void registryRecordTypeFindCallFunc(const iocshArgBuf *args) {
     printf("%p\n", (void*) registryRecordTypeFind(args[0].sval));
 }
 
 /* registryDeviceSupportFind */
 static const iocshFuncDef registryDeviceSupportFindFuncDef = {
-    "registryDeviceSupportFind",1,registryXxxFindArgs};
+    "registryDeviceSupportFind",
+    1,
+    registryXxxFindArgs,
+    "Prints the registry address of the device support given as first argument.\n\n"
+    "Example: registryDeviceSupportFind devAaiSoft\n",
+};
 static void registryDeviceSupportFindCallFunc(const iocshArgBuf *args) {
     printf("%p\n", (void*) registryDeviceSupportFind(args[0].sval));
 }
 
 /* registryDriverSupportFind */
 static const iocshFuncDef registryDriverSupportFindFuncDef = {
-    "registryDriverSupportFind",1,registryXxxFindArgs};
+    "registryDriverSupportFind",
+    1,
+    registryXxxFindArgs,
+    "Prints the registry address of the driver support given as first argument.\n\n"
+    "Example: registryDriverSupportFind stream\n",
+};
 static void registryDriverSupportFindCallFunc(const iocshArgBuf *args) {
     printf("%p\n", (void*) registryDriverSupportFind(args[0].sval));
 }
 
 /* registryFunctionFind */
 static const iocshFuncDef registryFunctionFindFuncDef = {
-    "registryFunctionFind",1,registryXxxFindArgs};
+    "registryFunctionFind",
+    1,
+    registryXxxFindArgs,
+    "Prints the registry address of the registered function given as first argument.\n\n"
+    "Example: registryFunctionFind registryFunctionFind\n",
+};
 static void registryFunctionFindCallFunc(const iocshArgBuf *args) {
     printf("%p\n", (void*) registryFunctionFind(args[0].sval));
 }

modules/database/src/template/top/exampleApp/src/_APPNAME_Hello.c

@@ -17,7 +17,17 @@ void hello(const char *name) {
 /* Information needed by iocsh */
 static const iocshArg     helloArg0 = {"name", iocshArgString};
 static const iocshArg    *helloArgs[] = {&helloArg0};
-static const iocshFuncDef helloFuncDef = {"hello", 1, helloArgs};
+static const iocshFuncDef helloFuncDef = {
+    "hello",
+    1,
+    helloArgs,
+#ifdef IOCSHFUNCDEF_HAS_USAGE
+    "Greet the person whose name is given as first argument.\n"
+    "If 'name' is unspecified, greet the world in general.\n\n"
+    "Example: hello\n"
+    "Example: hello stranger\n",
+#endif
+};
 
 /* Wrapper called by iocsh, selects the argument types that hello needs */
 static void helloCallFunc(const iocshArgBuf *args) {

modules/database/src/template/top/exampleApp/src/initTrace.c

@@ -28,7 +28,14 @@ int traceIocInit(void) {
 }
 
 
-static const iocshFuncDef traceInitFuncDef = {"traceIocInit", 0, NULL};
+static const iocshFuncDef traceInitFuncDef = {
+    "traceIocInit",
+    0,
+    NULL,
+    "Setup the 'iocInit' function to trace its different stages.\n"
+    "This function must be called before 'iocInit'.\n\n"
+    "Example: traceIocInit\n",
+};
 static void traceInitFunc(const iocshArgBuf *args) {
     traceIocInit();
 }

modules/database/src/tools/registerRecordDeviceDriver.pl

@@ -276,8 +276,15 @@ print $out (<< "END");
 /* $subname */
 static const iocshArg rrddArg0 = {"pdbbase", iocshArgPdbbase};
 static const iocshArg *rrddArgs[] = {&rrddArg0};
-static const iocshFuncDef rrddFuncDef =
-    {"$subname", 1, rrddArgs};
+static const iocshFuncDef rrddFuncDef = {
+    "$subname",
+    1,
+    rrddArgs,
+    "Register the various records, devices, for this DBD.\\n\\n"
+    "These are registered into the database given as first argument,\\n"
+    "which should always be 'pdbbase'.\\n\\n"
+    "Example: $subname pdbbase\\n",
+};
 static void rrddCallFunc(const iocshArgBuf *)
 {
     iocshSetError($subname(*iocshPpdbbase));