Overview

README.md

@@ -1,14 +1,28 @@
-[![Build Status](https://travis-ci.org/WebAssembly/spec.svg?branch=master)](https://travis-ci.org/WebAssembly/spec)
+[![Build Status](https://travis-ci.org/WebAssembly/multi-value.svg?branch=master)](https://travis-ci.org/WebAssembly/annotations)
+
+# Custom Annotations Proposal for WebAssembly
+
+This repository is a clone of [github.com/WebAssembly/spec/](https://github.com/WebAssembly/spec/).
+It is meant for discussion, prototype specification and implementation of a proposal to add support for custom annotations to the WebAssembly text format.
+
+See the [overview](proposals/annotations/Overview.md) for a summary of the proposal.
+
+Original `README` from upstream repository follows...
 
 # spec
 
-This repository holds the sources for the WebAssembly draft specification
-(to seed a future
-[WebAssembly Working Group](https://lists.w3.org/Archives/Public/public-new-work/2017Jun/0005.html)),
-a reference implementation, and the official testsuite.
+This repository holds a prototypical reference implementation for WebAssembly,
+which is currently serving as the official specification. Eventually, we expect
+to produce a specification either written in human-readable prose or in a formal
+specification language.
+
+It also holds the WebAssembly testsuite, which tests numerous aspects of
+conformance to the spec.
+
+View the work-in-progress spec at [webassembly.github.io/spec](https://webassembly.github.io/spec/).
 
-A formatted version of the spec is available here:
-[webassembly.github.io/spec](https://webassembly.github.io/spec/),
+At this time, the contents of this repository are under development and known
+to be "incomplet and inkorrect".
 
 Participation is welcome. Discussions about new features, significant semantic
 changes, or any specification change likely to generate substantial discussion

proposals/annotations/Overview.md

@@ -0,0 +1,70 @@
+# Custom Annotation Syntax for the Wasm Text Format
+
+## Motivation
+
+Problem
+
+* The Wasm binary format supports custom sections to enable associating arbitrary meta data with a Wasm module.
+
+* No equivalent exists for the text format. In particular, there is no way to
+  - represent custom sections themselves in the text format, cf. WebAssembly/design#1153 and https://gist.github.com/binji/d1cfff7faaebb2aa4f8b1c995234e5a0
+  - reflect arbitrary names in the text format, cf. WebAssembly/spec#617
+  - express information like for host bindings, cf. https://github.com/WebAssembly/host-bindings/blob/master/proposals/host-bindings/Overview.md
+
+Solution
+
+* This proposal adds the ability to decorate a module in textual notarion with arbitrary annotations of the form `(@id ...)`.
+
+* Neither the syntactic shape nor the semantics is prescribed by the Wasm specification, though the Appendix might include a description of optional support for name section annotations and generic custom sections.
+
+* This proposal only affects the text format, nothing else.
+
+
+## Details
+
+Extend the Text Format as follows:
+
+* Anywhere where white space is allowed, allow *annotations* of the following form:
+  ```
+  annot ::= "(@"idchar+  annotelem* ")"
+  annotelem ::= keyword | reserved | uN | sN | fN | string | id | "(" annotelem* ")" | "(@"idchar+ annotelem* ")"
+  ```
+  In other words, an annotation can contain any sequence of tokens, as long as it is well-bracketed.
+  No white space is allowed as part of the initial `(@idchar+` delimiter.
+
+* The initial `idchar+` is meant to be an identifier categorising the extension, and plays a role similar to the name of a custom section.
+  By convention, annotations corresponding to a custom section should use the same id.
+
+Extend the Appendix on the Custom Sections:
+
+* Define annotations reflecting the Name section, which take the form of annotations `(@name "name")`.
+  They may be placed after the binder for any construct that can be named by the name section.
+
+* Define annotation syntax expressing arbitrary custom sections; cf. https://gist.github.com/binji/d1cfff7faaebb2aa4f8b1c995234e5a0
+  As with any matter concerning annotations, it is up to implementations how they handle the case where an explicit custom section overlaps with individual annotations that are associated with the same custom section.
+
+
+## Examples
+
+Expressing generic custom sections (cf. https://gist.github.com/binji/d1cfff7faaebb2aa4f8b1c995234e5a0)
+```
+(module
+  (@custom "my-fancy-section" (after function) "contents-bytes")
+)
+```
+
+Expressing names
+```
+(module (@name "Gümüsü")
+  (func $lambda (@name "λ") (param $x (@name "α βγ δ") i32) (result i32) (get_local $x))
+)
+```
+
+Host bindings (cf. https://github.com/WebAssembly/host-bindings/blob/master/proposals/host-bindings/Overview.md)
+```
+(module
+  (func (export "f") (param i32 (@js unsigned)) ...)                        ;; argument converted as unsigned
+  (func (export "method") (param $x anyref (@js this)) (param $y i32) ...)  ;; maps this to first arg
+  (func (import "m" "constructor") (@js new) (param i32) (result anyref)    ;; is called as a constructor
+)
+```