Two readers decide how to use the Package, and neither reads its source.
The person who chooses, installs, and grants it, or their coding agent,
reads the Package’s readme. The model reads the declarations and
docs/readme.md through its documentation tool, seconds before it writes
a program nobody reviews. What each file leaves out, that reader guesses.
This guide shows you how to document a Package for both readers. The example is Pied Piper’s billing Package. Substitute your operations and your service.
Doc comments are the API
Section titled “Doc comments are the API”Every export and every field of a type the Package returns gets a doc
comment, and a function’s comment names each parameter with @param
and what it returns with @returns. The build warns about an export
without a comment, and about a comment that leaves a parameter or the
result out:
warning: parameter `customerId` is undocumented (missing `@param customerId`) --> packages/billing/src/lib.ts:22:29 |21 | */22 | export function applyCredit(customerId: string, amount: number): Credit { | ^^^^^^^^^^23 | if (amount <= 0) {submilli docs prints the comments, and the model’s documentation tool
returns them:
submilli docs @pied-piper/billing@pied-piper/billing — Goodwill credits for one customer of Pied Piper's billing service.
/** * Add a goodwill credit to a customer's account. * @param customerId The customer's id in the billing system, such as `pied_piper`. * @param amount The credit, in cents; must be positive. * @capability pied-piper.example/credits.apply { customerId: string, customerClass: string, amount: number } * @returns The credit as recorded, with the customer's balance after it. */function applyCredit(customerId: string, amount: number): Credit;
/** * A credit applied to a customer's account. */interface Credit { /** * Amount in cents. */ amount: number; /** * The customer's balance after the credit, in cents. Negative means Pied Piper owes the customer. */ balance: number; /** * The customer credited. */ customerId: string;}The first line is the description from submilli.toml. Write each comment
for a reader who sees only this. Say what the operation does, in which
unit, and what the fields mean.
The readme the model reads
Section titled “The readme the model reads”docs/readme.md is returned to the model with the declarations. Say what
the Package is for, what each operation takes and returns, when it
throws, what a denial means and that the program should stop, and end
with one complete main. Leave setup out: the model runs no install or
grant command and cannot change its blueprint, so those belong in the
Package’s root README.md, which people read.
# @pied-piper/billing
Credits for one customer of Pied Piper's billing service. The customer is theone the session was opened for; a credit for any other customer isrefused.
## applyCredit(customerId, amount)
Adds a goodwill credit of `amount` cents to the customer's account andreturns a `Credit` with the customer's balance afterwards. Throws`RangeError` if the amount is not positive, and `Error` if the customerdoes not exist.
A `PermissionDeniedError` means the blueprint does not allow this credit:the customer is not the session's, or the amount is more than the policyallows. Do not retry with another customer or amount; report it and stop.
```tsimport { applyCredit } from "@pied-piper/billing";
function main(): string { const credit = applyCredit("pied_piper", 1500); return `credited ${credit.amount} cents, balance ${credit.balance}`;}```Show each reader what it can call
Section titled “Show each reader what it can call”The model reads the Package’s documentation as its blueprint allows. An
operation the blueprint can’t allow is left out of the declarations,
together with the types only that operation uses. A function with several
@capability tags is shown only when the blueprint could allow every one
of them. An operation allowed only under a filter, or only after a person
approves, is shown with a line that says so.
The readme is yours to mark. Wrap a section about one operation in a region naming its capability, and a blueprint that can’t allow it doesn’t show the section:
<!-- submilli:if capability="pied-piper.example/credits.apply" -->
## applyCredit(customerId, amount)
Adds a goodwill credit of `amount` cents to the customer's account.
```tsimport { applyCredit } from "@pied-piper/billing";
function main(): string { return `balance ${applyCredit("pied_piper", 1500).balance}`;}```
<!-- submilli:endif -->Use all="<name> <name>" for an example that calls several operations,
and any="<name> <name>" for guidance shared by several. Text outside a
region is shown to every blueprint, so keep it true for a reader who can
call only some operations. The build checks every directive, and an
example inside a region is compiled like any other:
error: package `@pied-piper/billing` has malformed documentation directives: …/packages/billing/docs/readme.md:1: `pied-piper.example/credit.apply` is not a capability the standard library, this package, or its dependencies provideThe examples are compiled
Section titled “The examples are compiled”Every ts or typescript example in docs/readme.md is compiled
against the Package by submilli build test and counted as a test, so
an example can’t drift from the API it shows:
submilli build test -p @pied-piper/billingok packages/billing/tests/lib.test.ts :: refuses a zero amountok packages/billing/docs/readme.md :: example 1 (compile)
2 passed, 0 failed across 2 filesAn example that names a function the Package doesn’t have fails the run, with the line in the readme:
error: package `@pied-piper/billing` does not export `refund` --> packages/billing/docs/readme.md:28:10 |28 | import { refund } from "@pied-piper/billing"; | ^^^^^^help: exports: `Credit`, `applyCredit`FAIL packages/billing/docs/readme.md :: example 2 (compile)
2 passed, 1 failed across 2 filesExamples are compiled, not run. Mark a fragment that isn’t a complete
program as ts ignore and it is left alone.
The readme people read
Section titled “The readme people read”README.md in the Package’s directory is for the person deciding to use
the Package, and for the coding agent doing it for them. Replace the
scaffold’s placeholder. Say what the Package is for, which credential to
bind and how the service issues it, what the credential needs on the
service’s side, which operations to grant and the fields their filters
can test, and give the install and grant commands:
# @pied-piper/billing
Goodwill credits for Pied Piper's customers, on Stripe. Programs call`applyCredit(customerId, amount)`; the package reads the customer's classfrom the account and asks the blueprint before it credits anything.
## Credential
The package reads `BILLING_API_KEY`, a Stripe secret key. Create one inthe Stripe Dashboard under Developers → API keys; a restricted key needswrite access to Customers. Declare it in the blueprint and put the valuein the store:
```shsubmilli blueprint secret add BILLING_API_KEY --store billing_api_keysubmilli secret put billing_api_key```
## Operations
| Capability | Fields | Grant it for || --- | --- | --- || `pied-piper.example/credits.apply` | `customerId`, `customerClass`, `amount` | Credits to the session's customer |
Replace `OWNER/REPOSITORY` and `@OWNER/billing` with this Package's publishedrepository and name. Its scope must match the GitHub owner; use the same namein the commands below.
```shsubmilli install OWNER/REPOSITORY @OWNER/billingsubmilli blueprint add-package @OWNER/billing --no-capabilitiessubmilli blueprint capability add pied-piper.example/credits.apply \ --filter 'customerId == ${vars.customerId} and amount <= 5000'```Nothing compiles this file. When an operation changes, the compiled example catches the model’s readme, and this one is yours to review in the same change.