Problem
The template standard library is currently documented in docs/users-guide.md only as bulleted catalogues under "Use the template standard library" (path filters, collection filters, file tests, time helpers, impure helpers) plus the which / command_available / env / glob functions.
The only runnable, tested example is guide-stdlib-manifest, which exercises just with_suffix, uniq, and join. Every other helper — basename, dirname, relative_to, realpath, expanduser, contents, size, linecount, hash, digest, flatten, group_by, the file tests (file, dir, symlink, pipe, block_device, char_device, device), now, timedelta, fetch, shell, grep, which, command_available, env, and glob — relies on separate unit suites rather than on doc-example tests that prove the documented usage compiles and behaves as described.
This leaves the user-facing documentation thin on concrete, copy-pasteable usage for most of the standard library, and its examples are not gated by the documentation-example harness the rest of the guide enjoys.
Proposal
Create a comprehensive docs/stdlib-yaml-and-jinja-guide.md that:
- documents every registered helper in full, with concise prose and a concrete usage example per helper (name, signature, defaults, platform caveats, purity);
- provides runnable, tested examples using the existing
tested-example marker harness, exercised with the same real-binary-in-a-temp-workspace approach as the novice first-run flow tests (tests/novice_flow_smoke_tests.rs) and the documentation-example suites (tests/documentation_examples_*);
- registers each new example ID in the documentation-example registry so drift fails CI;
- is linked from
docs/users-guide.md (replacing/condensing the current catalogue in favour of a pointer plus a short overview) and from README.md.
Notes
- Some helpers touch the filesystem or network (
contents, size, linecount, hash, digest, realpath, file tests, glob, fetch, shell, grep). Tested examples for these will need fixtures or stubbed executables (see the stub pattern in tests/documentation_examples_e2e_tests.rs), and the network helpers should stay non-executing in tests.
- Hashing feature-gating (
legacy-digests → MD5/SHA-1) should be documented explicitly.
Context: raised from a completeness/accuracy assessment of docs/users-guide.md. The guide itself was found accurate; this is a coverage/completeness follow-up.
Problem
The template standard library is currently documented in
docs/users-guide.mdonly as bulleted catalogues under "Use the template standard library" (path filters, collection filters, file tests, time helpers, impure helpers) plus thewhich/command_available/env/globfunctions.The only runnable, tested example is
guide-stdlib-manifest, which exercises justwith_suffix,uniq, andjoin. Every other helper —basename,dirname,relative_to,realpath,expanduser,contents,size,linecount,hash,digest,flatten,group_by, the file tests (file,dir,symlink,pipe,block_device,char_device,device),now,timedelta,fetch,shell,grep,which,command_available,env, andglob— relies on separate unit suites rather than on doc-example tests that prove the documented usage compiles and behaves as described.This leaves the user-facing documentation thin on concrete, copy-pasteable usage for most of the standard library, and its examples are not gated by the documentation-example harness the rest of the guide enjoys.
Proposal
Create a comprehensive
docs/stdlib-yaml-and-jinja-guide.mdthat:tested-examplemarker harness, exercised with the same real-binary-in-a-temp-workspace approach as the novice first-run flow tests (tests/novice_flow_smoke_tests.rs) and the documentation-example suites (tests/documentation_examples_*);docs/users-guide.md(replacing/condensing the current catalogue in favour of a pointer plus a short overview) and fromREADME.md.Notes
contents,size,linecount,hash,digest,realpath, file tests,glob,fetch,shell,grep). Tested examples for these will need fixtures or stubbed executables (see the stub pattern intests/documentation_examples_e2e_tests.rs), and the network helpers should stay non-executing in tests.legacy-digests→ MD5/SHA-1) should be documented explicitly.Context: raised from a completeness/accuracy assessment of
docs/users-guide.md. The guide itself was found accurate; this is a coverage/completeness follow-up.