From 600a9c6416e77c60c8edc237593aa6d3fe9fad17 Mon Sep 17 00:00:00 2001
From: Kevin Lyda <kevin@lyda.ie>
Date: Mon, 26 May 2025 19:19:27 +0100
Subject: [PATCH] More docs for modules
---
ask/ask.go | 4 +++-
batch/batch.go | 17 ++++++++++++++++-
dclish/dclish.go | 33 ++++++++++++++++++++++++++++++++-
3 files changed, 51 insertions(+), 3 deletions(-)
diff --git a/ask/ask.go b/ask/ask.go
index 6581365..33e1cd4 100644
--- a/ask/ask.go
+++ b/ask/ask.go
@@ -1,6 +1,8 @@
/*
Package ask provides routines to ask questions of users. It handles
-getting a line of text, getting a choice from a liat and other things.
+getting a line of text, getting a choice from a list and other things.
+
+Underneath it uses the [github.com/chzyer/readline] module.
*/
package ask
diff --git a/batch/batch.go b/batch/batch.go
index 6de3eef..0176b7b 100644
--- a/batch/batch.go
+++ b/batch/batch.go
@@ -1,4 +1,19 @@
-// Package batch contains the non-interactive maintenence commands.
+// Package batch contains both interactive and non-interactive maintenence
+// commands.
+//
+// The interactive batch commands are as follows:
+//
+// - `install` does the initial install for bulletin. This will create
+// and seed the database and create the initial user. It will also
+// create the user's crontab entries.
+// - `new-user` creates a new user.
+//
+// The non-interactive batch commands are run from the user's crontab.
+//
+// - `reboot` is supposed to be run on system reboot and will delete
+// all shutdown messages.
+// - `expire` removes all expired messages and deletes broadcast messages
+// older than 3 days.
package batch
import (
diff --git a/dclish/dclish.go b/dclish/dclish.go
index 9f2096e..ecffd54 100644
--- a/dclish/dclish.go
+++ b/dclish/dclish.go
@@ -1,4 +1,35 @@
-// Package dclish A DCL-like command line parser.
+/*
+Package dclish A DCL-like command line parser.
+
+From the OpenVMS manual on how to parse a DCL command line.
+
+The following rules apply when entering DCL commands. Refer to
+Chapter 5 for information about using extended file names in DCL
+commands.
+
+ - Use any combination of uppercase and lowercase letters. The DCL
+ interpreter translates lowercase letters to uppercase. Uppercase and
+ lowercase characters in parameter and qualifier values are equivalent
+ unless enclosed in quotation marks (" ").
+ - Separate the command name from the first parameter with at least one
+ blank space or a tab.
+ - Separate each additional parameter from the previous parameter or
+ qualifier with at least one blank space or a tab.
+ - Begin each qualifier with a slash (/). The slash serves as a separator
+ and need not be preceded by blank spaces or tabs.
+ - If a parameter or qualifier value includes a blank space or a tab,
+ enclose the parameter or qualifier value in quotation marks.
+ - You cannot specify null characters (<NUL>) on a DCL command line,
+ even if you enclose the null character in quotation marks.
+ - Include no more than 127 elements (parameters, qualifiers, and qualifier
+ values) in each command line.
+ - Each element in a command must not exceed 255 characters. The entire
+ command must not exceed 1024 characters after all symbols1 and lexical
+ functions2 are converted to their values.
+ - You can abbreviate a command as long as the abbreviated name remains
+ unique among the defined commands on a system. DCL looks only at the
+ first four characters for uniqueness.
+*/
package dclish
import (
--
GitLab