use fully-qualified names in doc references (#58)

This allows e.g. `pdoc3` to turn them into the appropriate hyperlinks.

Signed-off-by: Joel Dice <joel.dice@fermyon.com>

Author: dicej

src/command.rs

@@ -71,6 +71,12 @@ pub struct Bindings {
     ///
     /// This will be created if it does not already exist.
     pub output_dir: PathBuf,
+
+    /// Optional name of top-level module to use for bindings.
+    ///
+    /// If this is not specified, the module name will be derived from the world name.
+    #[arg(long)]
+    pub world_module: Option<String>,
 }
 
 pub fn run<T: Into<OsString> + Clone, I: IntoIterator<Item = T>>(args: I) -> Result<()> {
@@ -87,6 +93,7 @@ fn generate_bindings(common: Common, bindings: Bindings) -> Result<()> {
             .wit_path
             .unwrap_or_else(|| Path::new("wit").to_owned()),
         common.world.as_deref(),
+        bindings.world_module.as_deref(),
         &bindings.output_dir,
     )
 }

src/lib.rs

@@ -167,12 +167,19 @@ impl Invoker for MyInvoker {
     }
 }
 
-pub fn generate_bindings(wit_path: &Path, world: Option<&str>, output_dir: &Path) -> Result<()> {
+pub fn generate_bindings(
+    wit_path: &Path,
+    world: Option<&str>,
+    world_module: Option<&str>,
+    output_dir: &Path,
+) -> Result<()> {
     let (resolve, world) = parse_wit(wit_path, world)?;
     let summary = Summary::try_new(&resolve, world)?;
-    let world_dir = output_dir.join(resolve.worlds[world].name.to_snake_case().escape());
+    let world_name = resolve.worlds[world].name.to_snake_case().escape();
+    let world_module = world_module.unwrap_or(&world_name);
+    let world_dir = output_dir.join(world_module.replace('.', "/"));
     fs::create_dir_all(&world_dir)?;
-    summary.generate_code(&world_dir, true)?;
+    summary.generate_code(&world_dir, world_module, true)?;
 
     Ok(())
 }
@@ -379,8 +386,6 @@ pub async fn componentize(
             .as_ref()
             .and_then(|(r, p, c)| c.bindings.as_deref().map(|f| (r, p, f)))
     {
-        summary.generate_code(world_dir.path(), false)?;
-
         let paths = python_path
             .iter()
             .enumerate()
@@ -401,18 +406,22 @@ pub async fn componentize(
             .filter_map(Result::transpose)
             .collect::<Result<Vec<_>>>()?;
 
+        let module = paths.first().unwrap().1.replace('/', ".");
+
+        summary.generate_code(world_dir.path(), &module, false)?;
+
         (
             paths
                 .iter()
                 .map(|(index, p)| format!("{index}/{p}"))
                 .collect::<Vec<_>>(),
-            paths.first().unwrap().1.replace('/', "."),
+            module,
         )
     } else {
         let module = resolve.worlds[world].name.to_snake_case();
         let world_dir = world_dir.path().join(&module);
         fs::create_dir_all(&world_dir)?;
-        summary.generate_code(&world_dir, false)?;
+        summary.generate_code(&world_dir, &module, false)?;
 
         (vec!["world".to_owned()], module)
     };

src/python.rs

@@ -29,13 +29,14 @@ fn python_componentize(
 
 #[pyo3::pyfunction]
 #[pyo3(name = "generate_bindings")]
-#[pyo3(signature = (wit_path, world, output_dir))]
+#[pyo3(signature = (wit_path, world, world_module, output_dir))]
 fn python_generate_bindings(
     wit_path: PathBuf,
     world: Option<&str>,
+    world_module: Option<&str>,
     output_dir: PathBuf,
 ) -> PyResult<()> {
-    crate::generate_bindings(&wit_path, world, &output_dir)
+    crate::generate_bindings(&wit_path, world, world_module, &output_dir)
         .map_err(|e| PyAssertionError::new_err(format!("{e:?}")))
 }
 

src/summary.rs

@@ -1,7 +1,7 @@
 use {
     crate::{
         abi::{self, MAX_FLAT_PARAMS, MAX_FLAT_RESULTS},
-        bindgen::DISPATCHABLE_CORE_PARAM_COUNT,
+        bindgen::{self, DISPATCHABLE_CORE_PARAM_COUNT},
         exports::exports::{
             self, Case, Constructor, Function, FunctionExport, LocalResource, OwnedKind, OwnedType,
             RemoteResource, Resource, Static, Symbols,
@@ -700,6 +700,8 @@ impl<'a> Summary<'a> {
 
     fn function_code(
         &self,
+        direction: Direction,
+        world_module: &str,
         function: &MyFunction,
         names: &mut TypeNames,
         seen: &HashSet<TypeId>,
@@ -733,6 +735,27 @@ impl<'a> Summary<'a> {
 
         let mut type_name = |ty| names.type_name(ty, seen, if self_ { resource } else { None });
 
+        let absolute_type_name = |ty| {
+            format!(
+                "{world_module}.{}.{}",
+                match direction {
+                    Direction::Import => "imports",
+                    Direction::Export => "exports",
+                },
+                TypeNames::new(self, TypeOwner::None).type_name(
+                    ty,
+                    &if let Type::Id(id) = ty {
+                        Some(bindgen::dealias(self.resolve, id))
+                    } else {
+                        None
+                    }
+                    .into_iter()
+                    .collect::<HashSet<_>>(),
+                    None
+                )
+            )
+        };
+
         let params = self_
             .then(|| "self".to_string())
             .into_iter()
@@ -767,7 +790,7 @@ impl<'a> Summary<'a> {
                     [ty] => match special_return(*ty) {
                         SpecialReturn::Result(result) => {
                             let error = if let Some(ty) = result.err {
-                                Some(type_name(ty))
+                                Some(absolute_type_name(ty))
                             } else {
                                 Some("None".into())
                             };
@@ -944,7 +967,12 @@ impl<'a> Summary<'a> {
         sorted
     }
 
-    pub fn generate_code(&self, path: &Path, stub_runtime_calls: bool) -> Result<()> {
+    pub fn generate_code(
+        &self,
+        path: &Path,
+        world_module: &str,
+        stub_runtime_calls: bool,
+    ) -> Result<()> {
         #[derive(Default)]
         struct Definitions<'a> {
             types: Vec<String>,
@@ -964,7 +992,10 @@ impl<'a> Summary<'a> {
         }
 
         let docstring = |docs: Option<&str>, indent_level, error: Option<&str>| {
-            let docs = match (docs, error.map(|e| format!("Raises: Err({e})"))) {
+            let docs = match (
+                docs,
+                error.map(|e| format!("Raises: `{world_module}.types.Err({e})`")),
+            ) {
                 (Some(docs), Some(error_docs)) => Some(format!("{docs}\n\n{error_docs}")),
                 (Some(docs), None) => Some(docs.to_owned()),
                 (None, Some(error_docs)) => Some(error_docs),
@@ -1070,20 +1101,14 @@ class {name}:
                         .collect::<Vec<_>>()
                         .join(", ");
 
-                    let docs = if let Some(docs) = &ty.docs.contents {
-                        docs.lines()
-                            .map(|line| format!("# {line}\n"))
-                            .collect::<Vec<_>>()
-                            .concat()
-                    } else {
-                        String::new()
-                    };
+                    let docs = docstring(ty.docs.contents.as_deref(), 0, None);
 
                     Code::Shared(format!(
                         "
 {classes}
 
-{docs}{camel} = Union[{cases}]
+{camel} = Union[{cases}]
+{docs}
 "
                     ))
                 }
@@ -1156,7 +1181,14 @@ class {camel}(Flag):
                                 static_method,
                                 result_count,
                                 error,
-                            } = self.function_code(function, &mut names, &seen, Some(id));
+                            } = self.function_code(
+                                Direction::Import,
+                                world_module,
+                                function,
+                                &mut names,
+                                &seen,
+                                Some(id),
+                            );
 
                             let docs = docstring(function.docs, 2, error.as_deref());
 
@@ -1271,7 +1303,14 @@ class {camel}:
                                 static_method,
                                 error,
                                 ..
-                            } = self.function_code(function, &mut names, &seen, Some(id));
+                            } = self.function_code(
+                                Direction::Export,
+                                world_module,
+                                function,
+                                &mut names,
+                                &seen,
+                                Some(id),
+                            );
 
                             let docs = docstring(function.docs, 2, error.as_deref());
 
@@ -1419,7 +1458,14 @@ class {camel}(Protocol):
                         result_count,
                         error,
                         ..
-                    } = self.function_code(function, &mut names, &seen, None);
+                    } = self.function_code(
+                        Direction::Import,
+                        world_module,
+                        function,
+                        &mut names,
+                        &seen,
+                        None,
+                    );
 
                     match function.kind {
                         FunctionKind::Import => {