Rewrite the comment about the generated main function.

Author: sunfishcode

macro/src/lib.rs

@@ -84,7 +84,7 @@ pub fn attr_macro_test(_attr: TokenStream, item: TokenStream) -> TokenStream {
     .into()
 }
 
-/// Enables a HTTP-server main function, for creating [HTTP servers].
+/// Enables a HTTP server main function, for creating [HTTP servers].
 ///
 /// [HTTP servers]: https://docs.rs/wstd/latest/wstd/http/server/index.html
 ///
@@ -148,9 +148,38 @@ pub fn attr_macro_http_server(_attr: TokenStream, item: TokenStream) -> TokenStr
 
         ::wstd::wasi::http::proxy::export!(TheServer with_types_in ::wstd::wasi);
 
-        // In case the user needs it, provide a `main` function so that the
-        // code compiles.
-        fn main() { unreachable!("HTTP-server components should be run wth `handle` rather than `main`") }
+        // Provide an actual function named `main`.
+        //
+        // WASI HTTP server components don't use a traditional `main` function.
+        // They export a function named `handle` which takes a `Request`
+        // argument, and which may be called multiple times on the same
+        // instance. To let users write a familiar `fn main` in a file
+        // named src/main.rs, we provide this `wstd::main` macro, which
+        // transforms the user's `fn main` into the appropriate `handle`
+        // function.
+        //
+        // However, when the top-level file is named src/main.rs, rustc
+        // requires there to be a function named `main` somewhere in it. This
+        // requirement can be disabled using `#![no_main]`, however we can't
+        // use that automatically because macros can't contain inner
+        // attributes, and we don't want to require users to add `#![no_main]`
+        // in their own code.
+        //
+        // So, we include a definition of a function named `main` here, which
+        // isn't intended to ever be called, and exists just to satify the
+        // requirement for a `main` function.
+        //
+        // Users could use `#![no_main]` if they want to. Or, they could name
+        // their top-level file src/lib.rs and add
+        // ```toml
+        // [lib]
+        // crate-type = ["cdylib"]
+        // ```
+        // to their Cargo.toml. With either of these, this "main" function will
+        // be ignored as dead code.
+        fn main() {
+            unreachable!("HTTP server components should be run with `handle` rather than `run`")
+        }
     }
     .into()
 }