From 091dff67643b34719bf91d2feeda0c6df3213d35 Mon Sep 17 00:00:00 2001
From: Mario Fetka <mario.fetka@gmail.com>
Date: Fri, 29 May 2026 10:32:40 +0200
Subject: [PATCH] net: document multicall command dispatch

Add comments to net.c describing the NET multicall dispatch table and helper
flow.

Document how commands are resolved through NET <command> and renamed/stub-style
argv[0] invocation, how the mode field is used by shared handlers, and why
NCOPY is currently not registered in the dispatcher.

No behavior change.
---
 net.c | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/net.c b/net.c
index 2f87a1d..4f2b769 100644
--- a/net.c
+++ b/net.c
@@ -32,6 +32,27 @@ char  prgpath[65];
 
 typedef int (*NET_FUNC)(int argc, char *argv[], int mode);
 
+/*
+ * net_functions
+ *
+ * Purpose:
+ *   Maps NET subcommands and stand-alone multicall executable names to their
+ *   implementation function. The same binary can be invoked either as NET
+ *   with the command name in argv[1], or through a renamed/stub executable
+ *   where argv[0] already contains the command name.
+ *
+ * Fields:
+ *   name        - uppercase command or alias name used for dispatch.
+ *   description - short text shown by the built-in usage listing.
+ *   func        - command implementation entry point.
+ *   mode        - small command-specific selector passed to shared handlers.
+ *
+ * Notes:
+ *   NCOPY is intentionally kept out of this table while the NCP74
+ *   server-side copy/open-handle path is still under investigation. Keeping
+ *   ncopy.c in the build makes it compile-tested, but removing the table entry
+ *   prevents accidental execution through NET/Multicall dispatch.
+ */
 static struct s_net_functions {
  char      *name;
  char      *description;
@@ -75,6 +96,18 @@ static struct s_net_functions {
 
 #define MAX_FUNCS  (sizeof(net_functions) / sizeof(struct s_net_functions))
 
+/*
+ * get_entry_nr
+ *
+ * Purpose:
+ *   Resolves a DOS program path or command token to an entry in the NET
+ *   dispatch table. The basename is extracted, an optional extension is
+ *   removed, and the result is uppercased before it is compared with the
+ *   registered command names.
+ *
+ * Returns:
+ *   The net_functions[] index on match, or -1 if the token is not registered.
+ */
 static int get_entry_nr(char *fstr)
 {
   int       entry    = MAX_FUNCS;
@@ -93,6 +126,24 @@ static int get_entry_nr(char *fstr)
   return(-1);
 }
 
+/*
+ * call_func_entry
+ *
+ * Purpose:
+ *   Attempts to dispatch argv[0] to a registered NET command. This supports
+ *   both stand-alone multicall-style invocations and the second pass from
+ *   main(), where argv is shifted so that NET subcommands are dispatched as if
+ *   they were executable names.
+ *
+ * Notes:
+ *   Most commands require IPX/requester initialization before they run. MAP is
+ *   allowed to run without a successful ipx_init() so it can report existing
+ *   mapping state and requester-related errors in the traditional utility
+ *   style.
+ *
+ * Returns:
+ *   The command result, or -0xff when no matching command was found.
+ */
 int call_func_entry(int argc, char *argv[])
 {
   int       funcmode;
@@ -114,6 +165,14 @@ int call_func_entry(int argc, char *argv[])
   return(result);
 }
 
+/*
+ * get_path
+ *
+ * Purpose:
+ *   Stores the directory part of argv[0] in the global prgpath buffer. Some
+ *   command handlers use this to locate companion files or command scripts
+ *   relative to the NET executable.
+ */
 static void get_path(char *path)
 {
   char buf[100];
@@ -122,6 +181,19 @@ static void get_path(char *path)
   get_path_fn(buf, prgpath, NULL);
 }
 
+/*
+ * main
+ *
+ * Purpose:
+ *   NET multicall entry point. First try to dispatch by argv[0], which handles
+ *   renamed/stub executables such as FLAG.EXE or NDIR.EXE. If that fails, try
+ *   again with argv shifted by one so "NET FLAG ..." and similar command
+ *   forms work through the same dispatch table.
+ *
+ * Returns:
+ *   The selected command's return code. If no command matches, print the
+ *   built-in usage list and return the not-found result.
+ */
 int main(int argc, char *argv[])
 {
   int result = -0xff;