API Docs: improve usability

[gmlewis]

When generating docs for a raw endpoint, the API Docs generator says:

This API processes unstructured HTTP requests and therefore has no explicit schema.

However, I think this could be improved to be more useful if it reported what it does know about the endpoint.

For example, this:

//encore:api public raw method=PUT path=/api/v1/babyships/:xid

could report the method and path of the endpoint even if it can't report the contents of the request body.

Additionally, the auto-generated godocs don't appear to be formatted similarly to https://pkg.go.dev/ and could be improved.

For example, this comment:

// ListBabyships implements the HMAC-protected GET endpoint that
// lists Babyships from the mothership.
//
// Supported query parameters (url-query-escaped):
//   after=* (any xid, timestamp, or string, e.g. "yesterday")
//   before=* (any xid, timestamp, or string, e.g. "yesterday")
//   limit=* (default is 1000)
//   project=* (a project name, e.g. "Project%20A")
//
//encore:api public raw method=GET path=/api/v1/babyships

currently renders like this:

whereas pkg.go.dev would break this up into multiple lines for better readability.

[gmlewis]

Additionally, the "Service"-level documentation is taken from the wrong comment.

For example, if I have this:

// -*- compile-command: "encore test -v ./..."; -*-

// Package babyship represents the `/api/v1/babyships` RESTful API endpoint
// on the mothership.
package babyships

The comment that gets shown on the API Docs page is the first one, not the second one (but it should indeed be the second one, the one that is tied directly to the "package" line).

[eandre]

Thanks @gmlewis! Those are really good points. We definitely want to improve the usefulness of the API docs for raw endpoints, so we'll take a look at fixing this. And contributions welcome of course if anyone's interested :)