improve rust psibase package docs

doc/psidk/src/development/services/rust-service/package.md

@@ -4,18 +4,28 @@ A [psibase package](../../../specifications/data-formats/package.md) may be comp
 
 `cargo psibase` reads the `[package.metadata.psibase]` section of `Cargo.toml`. At the minimum, `package-name` must be specified.
 
-The available fields are:
+## Available fields
 
-- `package-name`: Must be present on the top-level crate for the package.
+In the top-level crate:
+
+- `package-name`: Required.
 - `services`: A list of services to include in the psibase package.
-- `server`: May be present on any crate that builds a service. The value is a crate which will handle HTTP requests sent to this service. The other crate will be built and included in the current package.
-- `plugin`: May be present on any crate that builds a service. The value is a crate that should be built with `cargo component` and uploaded as `/plugin.wasm`
+
+In any crate that builds a service:
+
+- `server`: The value is a crate which will handle HTTP requests sent to this service. The other crate will be built and included in the current package. If HTTP requests are handled in the base service, it should reference the service. Can be omitted if service serves no HTTP requests.
+- `plugin`: The value is a crate that should be built with `cargo component` and uploaded as `/plugin.wasm`
 - `flags`: [Flags](../../../specifications/data-formats/package.md#serviceservicejson) for the service.
-- `postinstall`: An array of actions to run when the package is installed. May be specified on the top-level crate or on any service. Actions from a single `postinstall` will be run in order. The order of actions from multiple crates is unspecified.
 - `data`: An array of `{src, dst}` paths to upload to the service's subdomain. `src` is relative to the location of Cargo.toml. If `src` is a directory, its contents will be included recursively.
-- `dependencies`: Additional packages, not build by cargo, that the package depends on. May be specified on the top-level crate or on any service.
 
-Example:
+In top-level crate or any crate that builds a service:
+
+- `postinstall`: An array of actions to run when the package is installed. Actions from a single `postinstall` will be run in order. The order of actions from multiple crates is unspecified.
+- `dependencies`: Additional packages, not build by cargo, that the package depends on.
+
+## Example
+
+./Cargo.toml
 
 ```toml
 [package]
@@ -24,19 +34,32 @@ version = "0.1.0"
 description = "An example package"
 
 [package.metadata.psibase]
-# Builds example.psi
+# (required) Builds example.psi
 package-name = "example"
+# package includes `service1` service
+services = ["service1"]
+
+[package.metadata.psibase.dependencies]
+HttpServer = "0.13.0"
+```
+
+./service/Cargo.toml
+
+```toml
+[package]
+name = "service1"
+version = "0.1.0"
+description = "A service to be included in the package"
+
+[package.metadata.psibase]
 # Most services besides the core system services don't need extra flags.
 flags = []
 # This service handles its own HTTP requests
-server = "example"
+server = "service1"
 # Plugin for the front end
-plugin = "example-plugin"
-# Run the service's init action
-postinstall = [{sender="tpack", service="tpack", method="init", rawData="0000"}]
+plugin = "service1-plugin"
 # Upload the UI
-data = [{src = "ui/", dst = "/"}]
-
-[package.metadata.psibase.dependencies]
-HttpServer = "0.13.0"
+data = [{src = "../ui/dist", dst = "/"}]
+# Run the service's init action; "0000" represents <no args> from the Fracpack perspective.
+postinstall = [{sender="service1", service="service1", method="init", rawData="0000"}]
 ```

doc/psidk/src/development/services/rust-service/testing.md

@@ -43,6 +43,9 @@ mod service {
     }
 }
 
+/* packages takes a comma-delimited list and references the
+ * package.metadata.psibase.package-name (case-sensitive) in Cargo.toml).
+ * The test chain will be initialized with default packages + services listed here. */
 #[psibase::test_case(packages("example"))]
 fn test_arith(chain: psibase::Chain) -> Result<(), psibase::Error> {
     // Verify the actions work as expected.
@@ -68,7 +71,8 @@ fn test_arith(chain: psibase::Chain) -> Result<(), psibase::Error> {
 }
 ```
 
-Add the following to `Cargo.toml`. This will allow `cargo psibase` to build a psibase package from the crate.
+Add the following to `Cargo.toml`. This will allow `cargo psibase` to build a psibase package from the crate. See [Building Packages](package.md) for more details.
+
 ```toml
 [package.metadata.psibase]
 package-name = "example"