Improve the proposal repo layout.

.github/workflows/main.yml

@@ -11,6 +11,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
-    - uses: WebAssembly/wit-abi-up-to-date@v10
+    - uses: WebAssembly/wit-abi-up-to-date@v11
       with:
-        wit-abi-tag: wit-abi-0.8.0
+        wit-abi-tag: wit-abi-0.9.0

README.md

@@ -55,6 +55,8 @@ TODO before entering Phase 2.
 
 ### API walk-through
 
+The full API documentation can be found [here](wasi-proposal-template.md).
+
 [Walk through of how someone would use this API.]
 
 #### [Use case 1]

wasi-proposal-template.md

@@ -1,33 +1,60 @@
-# Import interface `proposal-interface-name`
-
-## Types
-
-## <a href="#api_type_one" name="api_type_one"></a> `api-type-one`: record
-
-Short description
-
-Explanation for developers using the API.
-
-Size: 16, Alignment: 8
-
-### Record Fields
-
-- <a href="api_type_one.property1" name="api_type_one.property1"></a> [`property1`](#api_type_one.property1): `u64`
-
-
-- <a href="api_type_one.property2" name="api_type_one.property2"></a> [`property2`](#api_type_one.property2): `string`
-
-
-## Functions
-
-----
-
-#### <a href="#api_function_one" name="api_function_one"></a> `api-function-one` 
-
-Short description
-
-Explanation for developers using the API.
-##### Results
-
-- <a href="#api_function_one.result0" name="api_function_one.result0"></a> `result0`: [`api-type-one`](#api_type_one)
-
+<h1><a name="wasi_proposal_template">World wasi-proposal-template</a></h1>
+<ul>
+<li>Imports:
+<ul>
+<li>interface <a href="#proposal_interface_name"><code>proposal-interface-name</code></a></li>
+</ul>
+</li>
+</ul>
+<h2><a name="proposal_interface_name">Import interface proposal-interface-name</a></h2>
+<p>Short interface description.</p>
+<p>Explanation for developers using the interface API. It should include an
+overview of the API as a whole as well as call out notable items in it,
+for example <a href="#example_api_type"><code>example-api-type</code></a> and <a href="#example_api_function"><code>example-api-function</code></a>.</p>
+<hr />
+<h3>Types</h3>
+<h4><a name="example_api_type"><code>record example-api-type</code></a></h4>
+<p>Short type description</p>
+<p>Explanation for developers using this type. It may be useful to give
+some examples of places in the API where the type is used, such as in
+the arguments and return type of <a href="#example_api_function"><code>example-api-function</code></a>.</p>
+<details>
+<summary>Detailed specification</summary>
+More rigorous specification details for implementers go here, if needed.
+The intention is to keep the developer-oriented docs focused on things that
+most developers will need to be aware of, while putting bulkier descriptions
+of precise behavior here.
+</details>
+<h5>Record Fields</h5>
+<ul>
+<li>
+<p><a name="example_api_type.property0"><code>property0</code></a>: <code>u64</code></p>
+<p>A description of a property.
+</li>
+<li>
+<p><a name="example_api_type.property1"><code>property1</code></a>: <code>string</code></p>
+<p>A description of another property.
+</li>
+</ul>
+<hr />
+<h3>Functions</h3>
+<h4><a name="example_api_function"><code>example-api-function: func</code></a></h4>
+<p>Short function description</p>
+<p>Explanation for developers using the API. This should describe the
+arguments which in this function are <code>arg0</code> and <code>arg1</code> and the return value.</p>
+<details>
+<summary>Detailed specification</summary>
+Similar to the details section above, this is meant for more rigorous
+specification details for implementors. This may explain what a compliant
+implementation MUST do, such as never returning an earlier result from a
+later call, for example.
+</details>
+<h5>Params</h5>
+<ul>
+<li><a name="example_api_function.arg0"><code>arg0</code></a>: <a href="#example_api_type"><a href="#example_api_type"><code>example-api-type</code></a></a></li>
+<li><a name="example_api_function.arg1"><code>arg1</code></a>: <code>string</code></li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="example_api_function.0"></a> result&lt;<a href="#example_api_type"><a href="#example_api_type"><code>example-api-type</code></a></a>&gt;</li>
+</ul>

wit/wasi-proposal-template.wit

@@ -0,0 +1,52 @@
+// Instructions for filling in this file:
+//
+//  - Delete all these `//` comments, up to the first `///` comment.
+//
+//  - Replace the remaining contents below with [Wit] code describing
+//    `interface`s and/or `world`s, using the same formatting style.
+//
+// If you want to include examples of the API in use, these should be in the
+// README.md at the root of the repository and linked to from this file.
+//
+// [Wit]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md
+
+/// Short interface description.
+///
+/// Explanation for developers using the interface API. It should include an
+/// overview of the API as a whole as well as call out notable items in it,
+/// for example `example-api-type` and `example-api-function`.
+default interface proposal-interface-name {
+    /// Short type description
+    ///
+    /// Explanation for developers using this type. It may be useful to give
+    /// some examples of places in the API where the type is used, such as in
+    /// the arguments and return type of `example-api-function`.
+    ///
+    /// <details>
+    /// <summary>Detailed specification</summary>
+    /// More rigorous specification details for implementers go here, if needed.
+    /// The intention is to keep the developer-oriented docs focused on things that
+    /// most developers will need to be aware of, while putting bulkier descriptions
+    /// of precise behavior here.
+    /// </details>
+    record example-api-type {
+        /// A description of a property.
+        property0: u64,
+        /// A description of another property.
+        property1: string,
+    }
+
+    /// Short function description
+    ///
+    /// Explanation for developers using the API. This should describe the
+    /// arguments which in this function are `arg0` and `arg1` and the return value.
+    ///
+    /// <details>
+    /// <summary>Detailed specification</summary>
+    /// Similar to the details section above, this is meant for more rigorous
+    /// specification details for implementors. This may explain what a compliant
+    /// implementation MUST do, such as never returning an earlier result from a
+    /// later call, for example.
+    /// </details>
+    example-api-function: func(arg0: example-api-type, arg1: string) -> result<example-api-type>
+}

wit/world.wit

@@ -0,0 +1,10 @@
+// If the repository defines `interface`s, this file can define a minimal world
+// which contains those interfaces, to allow documentation to be generated for
+// them.
+//
+// Proposals should remove these `//` commments, and edit the `world` name and
+// imports below to pull in their own `interface`s.
+
+default world wasi-proposal-template {
+    import proposal-interface-name: pkg.wasi-proposal-template.proposal-interface-name
+}