gen-markdown: Print world information, and tidy up formatting (#496)

- Start the output with the world name, world documentation, and a table
   of contents for the world.

 - Don't print type sizes and alignments, or flags bit numbers. A full
   description of the canonical ABI may be a useful thing to have, but the
   current document isn't really close to being that. As user-facing API
   documentation, it's confusing to have type sizes and alignments because
   these won't even be correct in some bindings.

 - Print function return value names, and call them return values, to avoid
   confusion with "result" which is a type.

 - Adjust various formatting details.

Author: sunfishcode

crates/bindgen-core/src/lib.rs

@@ -441,7 +441,7 @@ mod tests {
 pub trait WorldGenerator {
     fn generate(&mut self, resolve: &Resolve, id: WorldId, files: &mut Files) {
         let world = &resolve.worlds[id];
-        self.preprocess(resolve, &world.name);
+        self.preprocess(resolve, id);
 
         let mut funcs = Vec::new();
         let mut types = Vec::new();
@@ -473,9 +473,9 @@ pub trait WorldGenerator {
         self.finish(resolve, id, files);
     }
 
-    fn preprocess(&mut self, resolve: &Resolve, name: &str) {
+    fn preprocess(&mut self, resolve: &Resolve, world: WorldId) {
         drop(resolve);
-        drop(name);
+        drop(world);
     }
 
     fn import_interface(

crates/gen-guest-c/src/lib.rs

@@ -68,7 +68,8 @@ enum Scalar {
 }
 
 impl WorldGenerator for C {
-    fn preprocess(&mut self, resolve: &Resolve, name: &str) {
+    fn preprocess(&mut self, resolve: &Resolve, world: WorldId) {
+        let name = &resolve.worlds[world].name;
         self.world = name.to_string();
         self.sizes.fill(resolve);
     }

crates/gen-guest-rust/src/lib.rs

@@ -112,7 +112,7 @@ impl RustWasm {
 }
 
 impl WorldGenerator for RustWasm {
-    fn preprocess(&mut self, resolve: &Resolve, _name: &str) {
+    fn preprocess(&mut self, resolve: &Resolve, _world: WorldId) {
         self.types.analyze(resolve);
     }
 

crates/gen-guest-teavm-java/src/lib.rs

@@ -81,7 +81,8 @@ impl TeaVmJava {
 }
 
 impl WorldGenerator for TeaVmJava {
-    fn preprocess(&mut self, resolve: &Resolve, name: &str) {
+    fn preprocess(&mut self, resolve: &Resolve, world: WorldId) {
+        let name = &resolve.worlds[world].name;
         self.name = name.to_string();
         self.sizes.fill(resolve);
     }