[WebAssembly] Improve docs for wasm linker

[ruiu]

LGTM

docs/WebAssembly.rst

102

When building an executable, only the entry point and symbols ...?

[sbc100]

• spelling

[sbc100]

• feedback

docs/WebAssembly.rst

 WebAssembly lld port
 ====================
 
 The WebAssembly version of lld takes WebAssembly binaries as inputs and produces
 a WebAssembly binary as its output.  For the most part it tries to mimic the
 behaviour of traditional ELF linkers and specifically the ELF lld port.  Where
 possible that command line flags and the semantics should be the same.
 
 
 Object file format
 ------------------
 
 The format the input object files that lld expects is specified as part of the
-the WebAssembly tool conventions
-https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md.
+the WebAssembly tool conventions on linking_.
 
 This is object format that the llvm will produce when run with the
 ``wasm32-unknown-unknown`` target.  To build llvm with WebAssembly support
 currently requires enabling the experimental backed using
 ``-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD=WebAssembly``.
 
 
 Usage

 
 .. option:: --max-memory=<value>
 
   Maximum size of the linear memory. Default: unlimited.
 
 By default the function table is neither imported nor exported, but defined
 for internal use only.
 
-When building shared libraries symbols are exported if they are marked
-as ``visibility=default``.  When building executables only the entry point is
-exported by default.  In addition any symbol included on the command line via
-``--export`` is also exported.
+Bahaviour
+---------
+
+In general, where possible, the WebAssembly linker attempts to emulate the
+behavior of a traditional ELF linker, and in particular the ELF port of lld.
+For more specific details on how this is achieved see the tool conventions on
+linking_.
+
+Imports and Exports
+~~~~~~~~~~~~~~~~~~~
+
+When building a shared library any symbols marked as ``visibility=default`` will
+be exported.  When building an executable, only the entry point and symbols
+flagged as ``WASM_SYMBOL_EXPORTED`` are exported by default.  In LLVM the
+``WASM_SYMBOL_EXPORTED`` flag is applied to any symbol in the ``llvm.used`` list
+which corresponds to ``__attribute__((used))`` in C/C++ sources.
+
+In addition, symbols can be exported via the linker command line using
+``--export``.
+
+Finally, just like with native ELF linker the ``--export-dynamic`` flag can be
+used to export symbol in the executable which are marked as
+``visibility=default``.
+
+Garbage Collection
+~~~~~~~~~~~~~~~~~~
 
 Since WebAssembly is designed with size in mind the linker defaults to
 ``--gc-sections`` which means that all unused functions and data segments will
 be stripped from the binary.
 
 The symbols which are preserved by default are:
 
 - The entry point (by default ``_start``).
 - Any symbol which is to be exported.
 - Any symbol transitively referenced by the above.
 
 
 Missing features
 ----------------
 
 - Merging of data section similar to ``SHF_MERGE`` in the ELF world is not
   supported.
 - No support for creating shared libraries.  The spec for shared libraries in
   WebAssembly is still in flux:
   https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md
+
+.. _linking: https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md