iocsh: add usage messages

epics-base · Apr 25, 2020 · ce4fb60 · ce4fb60
1 parent cd32a7c
commit ce4fb60
Show file tree

Hide file tree

Showing 6 changed files with 164 additions and 62 deletions.
diff --git a/documentation/RELEASE_NOTES.md b/documentation/RELEASE_NOTES.md
@@ -14,6 +14,15 @@ release.
 
 ## EPICS Release 7.0.3.2
 
+### IOCsh usage messages
+
+`help <cmd>` now prints a descriptive usage message
+for many internal IOCsh commands.  Try `help *` to
+see them all.
+
+External code which wishes to provide a usage message
+should do so through the new `iocshFuncDef::usage` member.
+
 ### Variable names in RELEASE files
 
 `configure/RELEASE` files are parsed by both GNUmake and the `convertRelease.pl`

diff --git a/modules/database/src/ioc/as/asIocRegister.c b/modules/database/src/ioc/as/asIocRegister.c
@@ -19,7 +19,9 @@
 static const iocshArg asSetFilenameArg0 = { "ascf",iocshArgString};
 static const iocshArg * const asSetFilenameArgs[] = {&asSetFilenameArg0};
 static const iocshFuncDef asSetFilenameFuncDef =
-    {"asSetFilename",1,asSetFilenameArgs};
+    {"asSetFilename",1,asSetFilenameArgs,
+     "Set path+file name of ACF file.\n"
+     "No immediate effect.  Run as asInit() to (re)load.\n"};
 static void asSetFilenameCallFunc(const iocshArgBuf *args)
 {
     asSetFilename(args[0].sval);
@@ -29,21 +31,25 @@ static void asSetFilenameCallFunc(const iocshArgBuf *args)
 static const iocshArg asSetSubstitutionsArg0 = { "substitutions",iocshArgString};
 static const iocshArg * const asSetSubstitutionsArgs[] = {&asSetSubstitutionsArg0};
 static const iocshFuncDef asSetSubstitutionsFuncDef =
-    {"asSetSubstitutions",1,asSetSubstitutionsArgs};
+    {"asSetSubstitutions",1,asSetSubstitutionsArgs,
+     "Set subtitutions used when reading ACF file.\n"
+     "No immediate effect.  Run as asInit() to (re)load.\n"};
 static void asSetSubstitutionsCallFunc(const iocshArgBuf *args)
 {
     asSetSubstitutions(args[0].sval);
 }
 
 /* asInit */
-static const iocshFuncDef asInitFuncDef = {"asInit",0};
+static const iocshFuncDef asInitFuncDef = {"asInit",0,0,
+                                           "(Re)load ACF file.\n"};
 static void asInitCallFunc(const iocshArgBuf *args)
 {
     iocshSetError(asInit());
 }
 
 /* asdbdump */
-static const iocshFuncDef asdbdumpFuncDef = {"asdbdump",0};
+static const iocshFuncDef asdbdumpFuncDef = {"asdbdump",0,0,
+                                             "Dump processed ACF file (as read).\n"};
 static void asdbdumpCallFunc(const iocshArgBuf *args)
 {
     asdbdump();
@@ -52,7 +58,8 @@ static void asdbdumpCallFunc(const iocshArgBuf *args)
 /* aspuag */
 static const iocshArg aspuagArg0 = { "uagname",iocshArgString};
 static const iocshArg * const aspuagArgs[] = {&aspuagArg0};
-static const iocshFuncDef aspuagFuncDef = {"aspuag",1,aspuagArgs};
+static const iocshFuncDef aspuagFuncDef = {"aspuag",1,aspuagArgs,
+                                           "Show members of User Access Group.\n"};
 static void aspuagCallFunc(const iocshArgBuf *args)
 {
     aspuag(args[0].sval);
@@ -61,7 +68,8 @@ static void aspuagCallFunc(const iocshArgBuf *args)
 /* asphag */
 static const iocshArg asphagArg0 = { "hagname",iocshArgString};
 static const iocshArg * const asphagArgs[] = {&asphagArg0};
-static const iocshFuncDef asphagFuncDef = {"asphag",1,asphagArgs};
+static const iocshFuncDef asphagFuncDef = {"asphag",1,asphagArgs,
+                                           "Show members of Host Access Group.\n"};
 static void asphagCallFunc(const iocshArgBuf *args)
 {
     asphag(args[0].sval);
@@ -70,7 +78,8 @@ static void asphagCallFunc(const iocshArgBuf *args)
 /* asprules */
 static const iocshArg asprulesArg0 = { "asgname",iocshArgString};
 static const iocshArg * const asprulesArgs[] = {&asprulesArg0};
-static const iocshFuncDef asprulesFuncDef = {"asprules",1,asprulesArgs};
+static const iocshFuncDef asprulesFuncDef = {"asprules",1,asprulesArgs,
+                                             "List rules of an Access Security Group.\n"};
 static void asprulesCallFunc(const iocshArgBuf *args)
 {
     asprules(args[0].sval);
@@ -80,7 +89,8 @@ static void asprulesCallFunc(const iocshArgBuf *args)
 static const iocshArg aspmemArg0 = { "asgname",iocshArgString};
 static const iocshArg aspmemArg1 = { "clients",iocshArgInt};
 static const iocshArg * const aspmemArgs[] = {&aspmemArg0,&aspmemArg1};
-static const iocshFuncDef aspmemFuncDef = {"aspmem",2,aspmemArgs};
+static const iocshFuncDef aspmemFuncDef = {"aspmem",2,aspmemArgs,
+                                           "List members of Access Security Group.\n"};
 static void aspmemCallFunc(const iocshArgBuf *args)
 {
     aspmem(args[0].sval,args[1].ival);
@@ -89,9 +99,10 @@ static void aspmemCallFunc(const iocshArgBuf *args)
 /* astac */
 static const iocshArg astacArg0 = { "recordname",iocshArgString};
 static const iocshArg astacArg1 = { "user",iocshArgString};
-static const iocshArg astacArg2 = { "location",iocshArgString};
+static const iocshArg astacArg2 = { "host",iocshArgString};
 static const iocshArg * const astacArgs[] = {&astacArg0,&astacArg1,&astacArg2};
-static const iocshFuncDef astacFuncDef = {"astac",3,astacArgs};
+static const iocshFuncDef astacFuncDef = {"astac",3,astacArgs,
+                                          "Test Access Security privlages granted to user+host.\n"};
 static void astacCallFunc(const iocshArgBuf *args)
 {
     astac(args[0].sval,args[1].sval,args[2].sval);
@@ -100,7 +111,8 @@ static void astacCallFunc(const iocshArgBuf *args)
 /* ascar */
 static const iocshArg ascarArg0 = { "level",iocshArgInt};
 static const iocshArg * const ascarArgs[] = {&ascarArg0};
-static const iocshFuncDef ascarFuncDef = {"ascar",1,ascarArgs};
+static const iocshFuncDef ascarFuncDef = {"ascar",1,ascarArgs,
+                                          "Report status of PVs used in INP*() Access Security rules.\n"};
 static void ascarCallFunc(const iocshArgBuf *args)
 {
     ascar(args[0].ival);