docs: close documentation gaps in example source files

Large_File_Processing/python/delta_diff.py

@@ -13,6 +13,12 @@
 
 Both files are streamed with iterparse (constant memory). Exit code: 0 if the
 sets are identical, 1 if there are differences, 2 on usage error.
+
+FundsXML 4.x has no XML namespace — bare element names.
+Dependencies: lxml (`pip install lxml`); Python stdlib otherwise.
+Security: iterparse runs with resolve_entities=False, no_network=True
+(XXE / external-entity safe on untrusted feeds). The 0.005 tolerance absorbs
+2-dp rounding so re-exported numbers don't show as spurious "changed".
 """
 import json
 import sys

Large_File_Processing/python/split.py

@@ -10,6 +10,10 @@
 
 Useful for parallel downstream processing or staying under message-size limits.
 FundsXML 4.x has no XML namespace.
+
+Dependencies: lxml (`pip install lxml`); Python stdlib otherwise.
+Security: iterparse runs with resolve_entities=False, no_network=True
+(XXE / external-entity safe on untrusted feeds).
 """
 import sys
 from pathlib import Path

Large_File_Processing/python/stream_aggregate.py

@@ -9,6 +9,10 @@
 (the classic lxml fast_iter pattern). Prints the totals and peak RSS.
 
 FundsXML 4.x has no XML namespace — match the bare 'Position' tag.
+
+Dependencies: lxml (`pip install lxml`); Python stdlib otherwise.
+Security: iterparse runs with resolve_entities=False, no_network=True and
+huge_tree=False — XXE / entity-expansion safe even on untrusted feeds.
 """
 import resource
 import sys

XQuery_Examples/invocation/RunXQuery.java

@@ -6,6 +6,14 @@
 //   java  -cp "$SCP:/tmp/xq" RunXQuery <query.xq> <input.xml> [k=v ...]
 // Exit: 0 success, 2 setup error.
 //
+// Dependencies: Saxon-HE + xmlresolver jars only (fetched by
+//   tools/fetch-tools.sh into .lib/); no other libraries.
+//
+// This is a generic, FundsXML-agnostic XQuery runner: it binds the input as
+// the context item and passes string external variables — the FundsXML
+// specifics (no XML namespace, Position↔Asset by UniqueID) live in the .xq
+// files it runs. s9api is Saxon's idiomatic Java API; no JAXB.
+//
 // External query variables are passed as k=v args (string-typed), e.g. n=5.
 
 import java.io.File;

XSLT_DataQuality_Checks/Enhanced_Check/FundsXML_CompleteDQReport_HTML.xsl

@@ -1,4 +1,28 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!--
+  FundsXML Complete Data-Quality Report — HTML dashboard.
+
+  Purpose : one self-contained HTML page (10 sections) summarising the data
+            quality of a FundsXML document: control data, fund/share-class NAV
+            reconciliation, portfolio allocation, asset coverage, orphaned
+            positions / unused assets, identifier formats, date consistency.
+
+  Run     : deliberately **XSLT 1.0** for maximum processor compatibility (the
+            Basic_Checks report is XSLT 2.0 — this one runs anywhere):
+              xsltproc XSLT_DataQuality_Checks/Enhanced_Check/FundsXML_CompleteDQReport_HTML.xsl \
+                       FundsXML_Files/4.2.9/positions/Mixed-Fund_Positions.xml > report.html
+            Also works with Saxon, lxml (etree.XSLT), .NET XslCompiledTransform.
+            No parameters; output is method="html".
+
+  Depends : any XSLT 1.0 processor; no extension functions used.
+
+  FundsXML: FundsXML 4.x has NO XML namespace — all match/select use bare
+            element names. Positions and Assets are joined by a shared
+            <UniqueID>; the xsl:key definitions below index Assets by UniqueID
+            so orphaned positions / unused assets are flagged in O(1).
+            Tolerances mirror the Schematron / Basic XSLT (NAV sum < 1 ccy
+            unit, percentage sum within 1%, price calc < 0.1) — keep in sync.
+-->
 <xsl:stylesheet version="1.0"
                 xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 

XSLT_Transformations/invocation/RunTransform.java

@@ -6,8 +6,14 @@
 //   java  -cp "$SCP:/tmp/rt" RunTransform <stylesheet.xslt> <input.xml> <output> [k=v ...]
 // Exit: 0 success, 2 setup error.
 //
-// The repo's stylesheets are XSLT 2.0; Saxon supplies the engine. s9api is
-// Saxon's idiomatic Java API — no JAXB involved.
+// Dependencies: Saxon-HE + xmlresolver jars only (fetched by
+//   tools/fetch-tools.sh into .lib/); no other libraries.
+//
+// This is a generic, FundsXML-agnostic invocation wrapper: it applies any
+// stylesheet to any XML and passes through string parameters (k=v) — the
+// FundsXML specifics live in the .xslt files it runs. The repo's stylesheets
+// are XSLT 2.0; Saxon supplies the engine. s9api is Saxon's idiomatic Java
+// API — no JAXB involved (a full data binding would be needless here).
 
 import java.io.File;
 import net.sf.saxon.s9api.Processor;