From 0ecbf63a02ce625f8ad4254d3f26ad4c2994ed69 Mon Sep 17 00:00:00 2001
From: Harald Welte <laforge@osmocom.org>
Date: Fri, 3 Nov 2023 12:38:42 +0100
Subject: [PATCH] transport: Extend the documentation for each transport driver

This driver description we add to the code is automatically added to the
respective user manual sections.

Change-Id: I8807bfb11f43b167f1321d556e09ec5234fff629
---
 pySim/transport/calypso.py     | 5 ++++-
 pySim/transport/modem_atcmd.py | 4 +++-
 pySim/transport/pcsc.py        | 7 ++++++-
 pySim/transport/serial.py      | 4 +++-
 4 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/pySim/transport/calypso.py b/pySim/transport/calypso.py
index dd30f800..7544d2ec 100644
--- a/pySim/transport/calypso.py
+++ b/pySim/transport/calypso.py
@@ -167,6 +167,9 @@ class CalypsoSimLink(LinkBase):
 
     @staticmethod
     def argparse_add_reader_args(arg_parser: argparse.ArgumentParser):
-        osmobb_group = arg_parser.add_argument_group('OsmocomBB Reader')
+        osmobb_group = arg_parser.add_argument_group('OsmocomBB Reader', """Use an OsmocomBB compatible phone
+to access the SIM inserted to the phone SIM slot.  This will require you to run the OsmocomBB firmware inside
+the phone (can be ram-loaded).  It also requires that you run the ``osmocon`` program, which provides a unix
+domain socket to which this reader driver can attach.""")
         osmobb_group.add_argument('--osmocon', dest='osmocon_sock', metavar='PATH', default=None,
                                   help='Socket path for Calypso (e.g. Motorola C1XX) based reader (via OsmocomBB)')
diff --git a/pySim/transport/modem_atcmd.py b/pySim/transport/modem_atcmd.py
index 88e6253f..a05d6c45 100644
--- a/pySim/transport/modem_atcmd.py
+++ b/pySim/transport/modem_atcmd.py
@@ -180,7 +180,9 @@ class ModemATCommandLink(LinkBase):
 
     @staticmethod
     def argparse_add_reader_args(arg_parser: argparse.ArgumentParser):
-        modem_group = arg_parser.add_argument_group('AT Command Modem Reader')
+        modem_group = arg_parser.add_argument_group('AT Command Modem Reader', """Talk to a SIM Card inside a
+mobile phone or cellular modem which is attached to this computer and offers an AT command interface including
+the AT+CSIM interface for Generic SIM access as specified in 3GPP TS 27.007.""")
         modem_group.add_argument('--modem-device', dest='modem_dev', metavar='DEV', default=None,
                                  help='Serial port of modem for Generic SIM Access (3GPP TS 27.007)')
         modem_group.add_argument('--modem-baud', type=int, metavar='BAUD', default=115200,
diff --git a/pySim/transport/pcsc.py b/pySim/transport/pcsc.py
index 8a99e9f5..a6714d51 100644
--- a/pySim/transport/pcsc.py
+++ b/pySim/transport/pcsc.py
@@ -114,7 +114,12 @@ class PcscSimLink(LinkBase):
 
     @staticmethod
     def argparse_add_reader_args(arg_parser: argparse.ArgumentParser):
-        pcsc_group = arg_parser.add_argument_group('PC/SC Reader')
+        pcsc_group = arg_parser.add_argument_group('PC/SC Reader',
+        """Use a PC/SC card reader to talk to the SIM card.  PC/SC is a standard API for how applications
+access smart card readers, and is available on a variety of operating systems, such as Microsoft
+Windows, MacOS X and Linux.  Most vendors of smart card readers provide drivers that offer a PC/SC
+interface, if not even a generic USB CCID driver is used.  You can use a tool like ``pcsc_scan -r``
+to obtain a list of readers available on your system. """)
         dev_group = pcsc_group.add_mutually_exclusive_group()
         dev_group.add_argument('-p', '--pcsc-device', type=int, dest='pcsc_dev', metavar='PCSC', default=None,
                                help='Number of PC/SC reader to use for SIM access')
diff --git a/pySim/transport/serial.py b/pySim/transport/serial.py
index fbf907f5..06a082ab 100644
--- a/pySim/transport/serial.py
+++ b/pySim/transport/serial.py
@@ -244,7 +244,9 @@ class SerialSimLink(LinkBase):
 
     @staticmethod
     def argparse_add_reader_args(arg_parser: argparse.ArgumentParser):
-        serial_group = arg_parser.add_argument_group('Serial Reader')
+        serial_group = arg_parser.add_argument_group('Serial Reader', """Use a simple/ultra-low-cost serial reader
+attached to a (physical or USB/virtual) RS232 port.  This doesn't work with all RS232-attached smart card
+readers, only with the very primitive readers following the ancient `Phoenix` or `Smart Mouse` design.""")
         serial_group.add_argument('-d', '--device', metavar='DEV', default='/dev/ttyUSB0',
                                   help='Serial Device for SIM access')
         serial_group.add_argument('-b', '--baud', dest='baudrate', type=int, metavar='BAUD', default=9600,