docs: review feedback

x/auth/vesting/cmd/vestcalc/README.md

@@ -30,26 +30,47 @@ Run `go install` in this directory, which will create or update the
 [documentation](https://pkg.go.dev/cmd/go) for the `go` command-line
 tool for other options.
 
-## Writing a schedule
+## Schedule format
 
-When the `--write` flag is set, the tool will write a schedule to stdout.
-The format is the the format expected by the `create-periodic-vesting-account`
+Schedules are expressed in the format expected by the `create-periodic-vesting-account`
 or `create-clawback-vesting-account` cli commands, namely a JSON
 object with the members:
 
 - `"start_time"`: integer UNIX time;
-- `"periods"`: a JSON array of JSON objects with members:
-    - "coins": string giving the text coins format for the amount vested at this event;
+- `"periods"`: an array of objects describing vesting events with members:
+    - "coins": string giving the text coins format for the additional amount vested by this event;
     - "length_seconds": positive integer seconds from the last vesting event, or from the start time for the first vesting event.
 
+For instance:
+
+```
+{
+  "start_time": 1700000000,
+  "periods": [
+    {
+      "coins": "10000000uatom,500000000ubld",
+      "length_seconds": 2678400
+    },
+    {
+      "coins": "500000000ubld",
+      "length_seconds": 31536000
+    }
+  ]
+}
+
+```
+
+## Writing a schedule
+
+When the `--write` flag is set, the tool will write a schedule to stdout.
 The following flags control the output:
 
 - `--coins:` The total coins to vest, e.g. `100ubld,50urun`.
-- `--months`: The number of monthly to vesting events.
+- `--months`: The total number of months to complete vesting.
 - `--start`: The vesting start time: i.e. the first event happens in the
   next month. Specified in the format `YYYY-MM-DD` or `YYYY-MM-DDThh:mm`,
   e.g. `2006-01-02T15:04` for 3:04pm on January 2, 2006.
-- `--time`: The time of day of the vesting events, in 24-hour HH:MM format.
+- `--time`: The time of day (in the local timezone) of the vesting events, in 24-hour HH:MM format.
   Defaults to midnight.
 - `--cliffs`: Vesting cliffs in `YYYY-MM-DD` or `YYYY-MM-DDThh:mm`
   format. Only the latest one will have any effect, but it is useful to let
@@ -60,12 +81,12 @@ The vesting events will occur each month following the start time on the same
 day of the month (or the last day of the month, if the month does not have a
 sufficient number of days), for the specified number of months. The total coins
 to vest will be divided as evenly as possible among all the vesting events.
-Lastly, all events before the last cliff time, if any, are consolidated into a single even
+Lastly, all events before the last cliff time, if any, are consolidated into a single event
 at the last cliff time with the sum of the event amounts.
 
 ## Reading a schedule
 
-When the `--read` flag is set, the tool will read a schedule in JSON from
+When the `--read` flag is set, the tool will read a schedule from
 stdin and write the vesting events in absolute time to stdout.
 
 ## Examples

x/auth/vesting/cmd/vestcalc/vestcalc.go

@@ -13,7 +13,7 @@ import (
 	"github.com/cosmos/cosmos-sdk/x/auth/vesting/client/cli"
 )
 
-// vestcalc is a utility for creating or reading period files
+// vestcalc is a utility for creating or reading schedule files
 // for use in some vesting account types.  See README.md for usage.
 
 // divide returns the division of total as evenly as possible.
@@ -98,7 +98,7 @@ func divideCoins(coins sdk.Coins, divisor int) ([]sdk.Coins, error) {
 // monthlyVestTimes generates timestamps for successive months after startTime.
 // The monthly events occur at the given time of day. If the month is not
 // long enough for the desired date, the last day of the month is used.
-// The number of months must be postive.
+// The number of months must be positive.
 func monthlyVestTimes(startTime time.Time, months int, timeOfDay time.Time) ([]time.Time, error) {
 	if months < 1 {
 		return nil, fmt.Errorf("must have at least one vesting period")