From a722bb9289c73e41d3010c986ed5f300398cc959 Mon Sep 17 00:00:00 2001 From: Minijackson Date: Mon, 9 May 2022 14:45:58 -0700 Subject: [PATCH] treewide: add usage help to various iocsh functions --- modules/ca/src/client/acctstRegister.cpp | 8 +++- modules/database/src/ioc/db/dbIocRegister.c | 19 ++++++-- .../src/ioc/dbStatic/dbStaticIocRegister.c | 46 +++++++++++++++++-- .../src/ioc/dbtemplate/dbtoolsIocRegister.c | 15 ++++-- modules/database/src/ioc/misc/dlload.c | 8 +++- .../src/ioc/misc/iocshRegisterCommon.c | 15 +++++- .../src/ioc/registry/registryIocRegister.c | 28 +++++++++-- .../top/exampleApp/src/_APPNAME_Hello.c | 12 ++++- .../template/top/exampleApp/src/initTrace.c | 9 +++- .../src/tools/registerRecordDeviceDriver.pl | 11 ++++- 10 files changed, 148 insertions(+), 23 deletions(-) diff --git a/modules/ca/src/client/acctstRegister.cpp b/modules/ca/src/client/acctstRegister.cpp index c619f97bb..8f69d25bc 100644 --- a/modules/ca/src/client/acctstRegister.cpp +++ b/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 */ diff --git a/modules/database/src/ioc/db/dbIocRegister.c b/modules/database/src/ioc/db/dbIocRegister.c index ef57c5d44..7d056eebf 100644 --- a/modules/database/src/ioc/db/dbIocRegister.c +++ b/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)); diff --git a/modules/database/src/ioc/dbStatic/dbStaticIocRegister.c b/modules/database/src/ioc/dbStatic/dbStaticIocRegister.c index 6851d41fc..751b7b250 100644 --- a/modules/database/src/ioc/dbStatic/dbStaticIocRegister.c +++ b/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); diff --git a/modules/database/src/ioc/dbtemplate/dbtoolsIocRegister.c b/modules/database/src/ioc/dbtemplate/dbtoolsIocRegister.c index 8ee6b2c40..b6b0c30e6 100644 --- a/modules/database/src/ioc/dbtemplate/dbtoolsIocRegister.c +++ b/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)); diff --git a/modules/database/src/ioc/misc/dlload.c b/modules/database/src/ioc/misc/dlload.c index a03685526..544e46098 100644 --- a/modules/database/src/ioc/misc/dlload.c +++ b/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); diff --git a/modules/database/src/ioc/misc/iocshRegisterCommon.c b/modules/database/src/ioc/misc/iocshRegisterCommon.c index eba0678fa..c23510800 100644 --- a/modules/database/src/ioc/misc/iocshRegisterCommon.c +++ b/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" + "'_registerRecordDeviceDriver' which has been linked\n" + "into the process, e.g. by dynamic loading, or by linking with\n" + "a generated '_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)); diff --git a/modules/database/src/ioc/registry/registryIocRegister.c b/modules/database/src/ioc/registry/registryIocRegister.c index e45534fa7..250037ff2 100644 --- a/modules/database/src/ioc/registry/registryIocRegister.c +++ b/modules/database/src/ioc/registry/registryIocRegister.c @@ -21,28 +21,48 @@ static const iocshArg * const registryXxxFindArgs[1] = {®istryXxxFindArg0}; /* 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)); } diff --git a/modules/database/src/template/top/exampleApp/src/_APPNAME_Hello.c b/modules/database/src/template/top/exampleApp/src/_APPNAME_Hello.c index 16147980f..1cb7762e2 100644 --- a/modules/database/src/template/top/exampleApp/src/_APPNAME_Hello.c +++ b/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) { diff --git a/modules/database/src/template/top/exampleApp/src/initTrace.c b/modules/database/src/template/top/exampleApp/src/initTrace.c index 50bc8e8c7..64bc9cff7 100644 --- a/modules/database/src/template/top/exampleApp/src/initTrace.c +++ b/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(); } diff --git a/modules/database/src/tools/registerRecordDeviceDriver.pl b/modules/database/src/tools/registerRecordDeviceDriver.pl index f95230dee..076ba9d21 100644 --- a/modules/database/src/tools/registerRecordDeviceDriver.pl +++ b/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));