complete the source code review

howto/ldap.md

@@ -408,12 +408,16 @@ See also: <https://gitlab.torproject.org/tpo/tpa/team/-/issues/33766>
 
 ### Source file analysis
 
-TODO: document those tools.
+Those are the various scripts shipped by userdir-ldap. This table
+describes which programming language it's written in and a short
+description of its purpose. The `ud?` column documents whether the
+command was considered for implementation in ud, and gives us a hint
+on whether it is important or not.
 
 | tool                      | lang   | ud? | description                                                     |
 | ------------------------- | ------ | --- | --------------------------------------------------------------- |
-| `ud-arbimport`            | Python |     | possible example of direct   LDAP (write) access from Python    |
-| `ud-config`               | Python |     | prints config from `userdir-ldap.conf`, used by ud-replicate    |
+| `ud-arbimport`            | Python |     | import arbitrary entries into LDAP                              |
+| `ud-config`               | Python |     | prints config from `userdir-ldap.conf`, used by `ud-replicate`  |
 | `ud-echelon`              | Python | x   | "Watches for email activity from Debian Developers"             |
 | `ud-fingerserv`           | Perl   | x   | [finger(1)][] server to expose some (public) user information   |
 | `ud-fingerserv2.c`        | C      |     | same in C?                                                      |
@@ -442,24 +446,6 @@ TODO: document those tools.
 | `ud-xearth`               | Python |     | generates xearth DB from LDAP entries                           |
 | `ud-zoneupdate`           | Shell  | x   | increments serial on a zonefile and reload bind                 |
 
-The `ud?` column documents whether the command was considered for
-implementation in ud, and gives us a hint on whether it is important
-or not.
-
-| libraries               | lang   | description                                  |
-| ----------------------- | ------ | -------------------------------------------- |
-| `UDLdap.py`             | Python | mainly an Account representation             |
-| `userdir_exceptions.py` | Python | exceptions                                   |
-| `userdir_gpg.py`        | Python | yet another GnuPG Python wrapper             |
-| `userdir_ldap.py`       | Python | various functions to talk with LDAP and more |
-
-| configuration files          | lang   | description                                                             |
-| ---------------------------- | ------ | ----------------------------------------------------------------------- |
-| `userdir-ldap.conf`          | Python | LDAP host, admin user, email, logging, keyrings, web, DNS, MX, and more |
-| `userdir_ldap.pth`           | ???    | no idea!                                                                |
-| `userdir-ldap.schema`        | LDAP   | TPO/Debian-specific LDAP schema additions                               |
-| `userdir-ldap-slapd.conf.in` | slapd  | slapd configuration, includes LDAP access control                       |
-
 Note how the `ud-guest-upgrade` command works. It generates an LDAP
 snippet like:
 
@@ -477,6 +463,26 @@ where the `guest` gid is replaced by the "default" `defaultgroup`
 set in the `userdir-ldap.conf` file.
 
 [finger(1)]: https://manpages.debian.org/finger.1
+
+Those are other files in the source distribution which are not
+directly visible to users but are used as libraries by other files.
+
+| libraries               | lang   | description                                  |
+| ----------------------- | ------ | -------------------------------------------- |
+| `UDLdap.py`             | Python | mainly an Account representation             |
+| `userdir_exceptions.py` | Python | exceptions                                   |
+| `userdir_gpg.py`        | Python | yet another GnuPG Python wrapper             |
+| `userdir_ldap.py`       | Python | various functions to talk with LDAP and more |
+
+Those are the configuration files shipped with the package:
+
+| configuration files          | lang   | description                                                             |
+| ---------------------------- | ------ | ----------------------------------------------------------------------- |
+| `userdir-ldap.conf`          | Python | LDAP host, admin user, email, logging, keyrings, web, DNS, MX, and more |
+| `userdir_ldap.pth`           | ???    | no idea!                                                                |
+| `userdir-ldap.schema`        | LDAP   | TPO/Debian-specific LDAP schema additions                               |
+| `userdir-ldap-slapd.conf.in` | slapd  | slapd configuration, includes LDAP access control                       |
+
 ### References
 
  * [userdir-ldap source code](https://salsa.debian.org/dsa-team/mirror/userdir-ldap)