docs: various readability improvements (#1854)

Author: sudomateo

docs/howto/ddl.md

@@ -1,6 +1,7 @@
 # Modifying the database schema
 
-sqlc understands `ALTER TABLE` statements when parsing SQL.
+sqlc parses `CREATE TABLE` and `ALTER TABLE` statements in order to generate
+the necessary code.
 
 ```sql
 CREATE TABLE authors (
@@ -24,8 +25,11 @@ type Writer struct {
 
 ## Handling SQL migrations
 
-sqlc will ignore rollback statements when parsing migration SQL files. The
-following tools are current supported:
+sqlc does not perform database migrations for you. However, sqlc is able to
+differentiate between up and down migrations. sqlc ignores down migrations when
+parsing SQL files.
+
+sqlc supports parsing migrations from the following tools:
 
 - [dbmate](https://github.com/amacneil/dbmate)
 - [golang-migrate](https://github.com/golang-migrate/migrate)
@@ -98,17 +102,26 @@ type Comment struct {
 
 ### golang-migrate
 
-Warning: [golang-migrate specifies](https://github.com/golang-migrate/migrate/blob/master/MIGRATIONS.md#migration-filename-format) that the version number in the migration file name is to be interpreted numerically. However, sqlc executes the migration files in **lexicographic** order. If you choose to simply enumerate your migration versions, make sure to prepend enough zeros to the version number to avoid any unexpected behavior.
+**Warning:**
+[golang-migrate interprets](https://github.com/golang-migrate/migrate/blob/master/MIGRATIONS.md#migration-filename-format)
+migration filenames numerically. However, sqlc parses migration files in
+lexicographic order. If you choose to have sqlc enumerate your migration files,
+make sure their numeric ordering matches their lexicographic ordering to avoid
+unexpected behavior. This can be done by prepending enough zeroes to the
+migration filenames.
+
+This doesn't work as intended.
 
-Probably doesn't work as intended:
 ```
 1_initial.up.sql
 ...
 9_foo.up.sql
-# this migration file will be executed BEFORE 9_foo
+# this migration file will be parsed BEFORE 9_foo
 10_bar.up.sql
 ```
-Works as was probably intended:
+
+This worked as intended.
+
 ```
 001_initial.up.sql
 ...

docs/reference/config.md

@@ -35,7 +35,7 @@ Each mapping in the `sql` collection has the following keys:
 - `queries`:
   - Directory of SQL queries or path to single SQL file; or a list of paths.
 - `gen`:
-  - A mapping to configure built-in code generators. Supports the following keys:
+  - A mapping to configure built-in code generators. See [gen](#gen) for the supported keys.
 - `strict_function_checks`
   - If true, return an error if a called SQL function does not exist. Defaults to `false`.
 

docs/tutorials/getting-started-postgresql.md

@@ -16,17 +16,20 @@ directory. In our new directory, create a file named `sqlc.yaml` with the
 following contents:
 
 ```yaml
-version: 1
-packages:
-  - path: "tutorial"
-    name: "tutorial"
-    engine: "postgresql"
-    schema: "schema.sql"
+version: "2"
+sql:
+  - engine: "postgresql"
     queries: "query.sql"
+    schema: "schema.sql"
+    gen:
+      go:
+        package: "tutorial"
+        out: "tutorial"
 ```
 
-sqlc needs to know your database schema and queries. In the same directory,
-create a file named `schema.sql` with the following contents:
+sqlc needs to know your database schema and queries in order to generate code.
+In the same directory, create a file named `schema.sql` with the following
+content:
 
 ```sql
 CREATE TABLE authors (
@@ -60,25 +63,29 @@ DELETE FROM authors
 WHERE id = $1;
 ```
 
-For SQL UPDATE if you do not want to return the updated record to the user, add this to the `query.sql` file:
+If you **do not** want your SQL `UPDATE` queries to return the updated record
+to the user, add this to `query.sql`:
+
 ```sql
 -- name: UpdateAuthor :exec
 UPDATE authors
-set name = $2,
-bio = $3
+  set name = $2,
+  bio = $3
 WHERE id = $1;
 ```
-Otherwise, to return the updated record back to the user, add this to the `query.sql` file:
+
+Otherwise, to return the updated record to the user, add this to `query.sql`:
+
 ```sql
 -- name: UpdateAuthor :one
 UPDATE authors
-set name = $2,
-bio = $3
+  set name = $2,
+  bio = $3
 WHERE id = $1
 RETURNING *;
 ```
 
-You are now ready to generate code. Run the `generate` command. You shouldn't see any errors or output.
+You are now ready to generate code. You shouldn't see any errors or output.
 
 ```shell
 sqlc generate
@@ -165,5 +172,6 @@ go get github.com/lib/pq
 go build ./...
 ```
 
-To make that possible, sqlc generates readable, **idiomatic** Go code that you
-otherwise would have had to write yourself. Take a look in `tutorial/query.sql.go`.
+sqlc generates readable, **idiomatic** Go code that you otherwise would have
+had to write yourself. Take a look in the `tutorial` package to see what code
+sqlc generated.