Print public type names when generating documentation

Author: GearsDatapacks

compiler-core/src/analyse.rs

@@ -1403,19 +1403,24 @@ impl<'a, A> ModuleAnalyzer<'a, A> {
                 },
             )?;
 
-            environment.insert_type_alias(
-                name.clone(),
-                TypeAliasConstructor {
-                    origin: *location,
-                    module: self.module_name.clone(),
-                    type_,
-                    publicity: *publicity,
-                    deprecation: deprecation.clone(),
-                    documentation: documentation.as_ref().map(|(_, doc)| doc.clone()),
-                    arity,
-                    parameters,
-                },
-            )?;
+            let alias = TypeAliasConstructor {
+                origin: *location,
+                module: self.module_name.clone(),
+                type_,
+                publicity: *publicity,
+                deprecation: deprecation.clone(),
+                documentation: documentation.as_ref().map(|(_, doc)| doc.clone()),
+                arity,
+                parameters,
+            };
+
+            environment.names.maybe_register_reexport_alias(
+                &environment.current_package,
+                &name,
+                &alias,
+            );
+
+            environment.insert_type_alias(name.clone(), alias)?;
 
             if let Some(name) = hydrator.unused_type_variables().next() {
                 return Err(Error::UnusedTypeAliasParameter {

compiler-core/src/docs/printer.rs

@@ -15,7 +15,8 @@ use crate::{
     docvec,
     pretty::{Document, Documentable, break_, join, line, nil, zero_width_string},
     type_::{
-        Deprecation, PRELUDE_MODULE_NAME, PRELUDE_PACKAGE_NAME, Type, TypeVar, printer::Names,
+        Deprecation, PRELUDE_MODULE_NAME, PRELUDE_PACKAGE_NAME, Type, TypeVar,
+        printer::{Names, PrintMode},
     },
 };
 
@@ -279,8 +280,11 @@ impl Printer<'_> {
 
         let arguments = constructor.arguments.iter().map(
             |RecordConstructorArg { label, type_, .. }| match label {
-                Some((_, label)) => self.variable(label).append(": ").append(self.type_(type_)),
-                None => self.type_(type_),
+                Some((_, label)) => self
+                    .variable(label)
+                    .append(": ")
+                    .append(self.type_(type_, PrintMode::Normal)),
+                None => self.type_(type_, PrintMode::Normal),
             },
         );
 
@@ -309,7 +313,9 @@ impl Printer<'_> {
             self.title(name),
             parameters,
             " =",
-            line().append(self.type_(type_)).nest(INDENT)
+            line()
+                .append(self.type_(type_, PrintMode::ExpandAliases))
+                .nest(INDENT)
         ]
     }
 
@@ -320,7 +326,7 @@ impl Printer<'_> {
             self.keyword("pub const "),
             self.title(name),
             ": ",
-            self.type_(type_)
+            self.type_(type_, PrintMode::Normal)
         ]
     }
 
@@ -340,7 +346,7 @@ impl Printer<'_> {
         } else {
             Self::wrap_arguments(arguments.iter().map(|argument| {
                 let name = self.variable(self.argument_name(argument));
-                docvec![name, ": ", self.type_(&argument.type_)].group()
+                docvec![name, ": ", self.type_(&argument.type_, PrintMode::Normal)].group()
             }))
         };
 
@@ -349,7 +355,7 @@ impl Printer<'_> {
             self.title(name),
             arguments,
             " -> ",
-            self.type_(return_type)
+            self.type_(return_type, PrintMode::Normal)
         ]
         .group()
     }
@@ -387,7 +393,7 @@ impl Printer<'_> {
             .surround("(", ")")
     }
 
-    fn type_(&mut self, type_: &Type) -> Document<'static> {
+    fn type_(&mut self, type_: &Type, print_mode: PrintMode) -> Document<'static> {
         match type_ {
             Type::Named {
                 package,
@@ -397,27 +403,62 @@ impl Printer<'_> {
                 publicity,
                 ..
             } => {
-                let name = self.named_type_name(publicity, package, module, name);
+                let name = match print_mode {
+                    // If we are printing a type for a type alias, and the alias
+                    // is reexporting an internal type, we want to show that it
+                    // is aliasing that internal type, rather than showing it as
+                    // aliasing itself.
+                    PrintMode::ExpandAliases if *package == self.package => {
+                        self.named_type_name(publicity, package, module, name)
+                    }
+                    // If we are printing a type alias which aliases an internal
+                    // type from a different package, we still want to print the
+                    // public name for that type. If we are not printing a type
+                    // alias at all, we also want to use the public name.
+                    PrintMode::ExpandAliases | PrintMode::Normal => {
+                        // If we are using a reexported internal type, we want to
+                        // print it public name, whether it is from this package
+                        // or otherwise.
+                        if let Some((module, alias)) =
+                            self.names.reexport_alias(module.clone(), name.clone())
+                        {
+                            self.named_type_name(&Publicity::Public, package, module, alias)
+                        } else {
+                            self.named_type_name(publicity, package, module, name)
+                        }
+                    }
+                };
+
                 if arguments.is_empty() {
                     name
                 } else {
                     name.append(Self::type_arguments(
-                        arguments.iter().map(|argument| self.type_(argument)),
+                        arguments
+                            .iter()
+                            .map(|argument| self.type_(argument, PrintMode::Normal)),
                     ))
                 }
             }
             Type::Fn { arguments, return_ } => docvec![
                 self.keyword("fn"),
-                Self::type_arguments(arguments.iter().map(|argument| self.type_(argument))),
+                Self::type_arguments(
+                    arguments
+                        .iter()
+                        .map(|argument| self.type_(argument, PrintMode::Normal))
+                ),
                 " -> ",
-                self.type_(return_)
+                self.type_(return_, PrintMode::Normal)
             ],
             Type::Tuple { elements } => docvec![
                 "#",
-                Self::type_arguments(elements.iter().map(|element| self.type_(element))),
+                Self::type_arguments(
+                    elements
+                        .iter()
+                        .map(|element| self.type_(element, PrintMode::Normal))
+                ),
             ],
             Type::Var { type_ } => match type_.as_ref().borrow().deref() {
-                TypeVar::Link { type_ } => self.type_(type_),
+                TypeVar::Link { type_ } => self.type_(type_, PrintMode::Normal),
 
                 TypeVar::Unbound { id } | TypeVar::Generic { id } => {
                     let name = self.type_variable(*id);

compiler-core/src/docs/snapshots/gleam_core__docs__tests__function_uses_reexport_of_internal_type.snap

@@ -0,0 +1,29 @@
+---
+source: compiler-core/src/docs/tests.rs
+expression: output
+---
+---- SOURCE CODE
+-- thepackage/internal.gleam
+pub type Internal
+
+-- main.gleam
+
+import thepackage/internal
+
+pub type External = internal.Internal
+
+pub fn do_thing(value: internal.Internal) -> External {
+  value
+}
+
+
+---- TYPES
+
+--- External
+<pre><code>pub type External =
+  @internal Internal</code></pre>
+
+---- VALUES
+
+--- do_thing
+<pre><code>pub fn do_thing(value: <a href="#External">External</a>) -> <a href="#External">External</a></code></pre>

compiler-core/src/docs/snapshots/gleam_core__docs__tests__function_uses_reexport_of_internal_type_in_other_module.snap

@@ -0,0 +1,28 @@
+---
+source: compiler-core/src/docs/tests.rs
+expression: output
+---
+---- SOURCE CODE
+-- thepackage/internal.gleam
+pub type Internal
+
+-- thepackage/something.gleam
+
+import thepackage/internal
+
+pub type External = internal.Internal
+
+
+-- main.gleam
+
+import thepackage/something
+
+pub fn do_thing(value: something.External) {
+  value
+}
+
+
+---- VALUES
+
+--- do_thing
+<pre><code>pub fn do_thing(value: <a href="thepackage/something.html#External" title="thepackage/something.{type External}">something.External</a>) -> <a href="thepackage/something.html#External" title="thepackage/something.{type External}">something.External</a></code></pre>

compiler-core/src/docs/snapshots/gleam_core__docs__tests__use_reexport_from_other_package.snap

@@ -0,0 +1,27 @@
+---
+source: compiler-core/src/docs/tests.rs
+expression: output
+---
+---- SOURCE CODE
+-- some_package/internal.gleam
+pub type Internal
+
+-- some_package/api.gleam
+
+import some_package/internal
+pub type External = internal.Internal
+
+
+-- main.gleam
+
+import some_package/api
+
+pub fn do_thing(value: api.External) {
+  value
+}
+
+
+---- VALUES
+
+--- do_thing
+<pre><code>pub fn do_thing(value: <a href="https://hexdocs.pm/some_package/1.0.0/some_package/api.html#External" title="some_package/api.{type External}">api.External</a>) -> <a href="https://hexdocs.pm/some_package/1.0.0/some_package/api.html#External" title="some_package/api.{type External}">api.External</a></code></pre>

compiler-core/src/docs/tests.rs

@@ -1123,6 +1123,69 @@ pub type External =
     );
 }
 
+#[test]
+fn use_reexport_from_other_package() {
+    assert_documentation!(
+        ("some_package", "some_package/internal", "pub type Internal"),
+        (
+            "some_package",
+            "some_package/api",
+            "
+import some_package/internal
+pub type External = internal.Internal
+"
+        ),
+        "
+import some_package/api
+
+pub fn do_thing(value: api.External) {
+  value
+}
+",
+        ONLY_LINKS
+    );
+}
+
+#[test]
+fn function_uses_reexport_of_internal_type() {
+    assert_documentation!(
+        ("thepackage/internal", "pub type Internal"),
+        "
+import thepackage/internal
+
+pub type External = internal.Internal
+
+pub fn do_thing(value: internal.Internal) -> External {
+  value
+}
+",
+        ONLY_LINKS
+    );
+}
+
+#[test]
+fn function_uses_reexport_of_internal_type_in_other_module() {
+    assert_documentation!(
+        ("thepackage/internal", "pub type Internal"),
+        (
+            "thepackage/something",
+            "
+import thepackage/internal
+
+pub type External = internal.Internal
+"
+        ),
+        "
+import thepackage/something
+
+pub fn do_thing(value: something.External) {
+  value
+}
+",
+        ONLY_LINKS
+    );
+}
+
 #[test]
 fn constructor_with_long_types_and_many_fields() {
     assert_documentation!(

compiler-core/src/language_server/tests/action.rs

@@ -9894,3 +9894,34 @@ pub fn make_wibble(x) {
         find_position_of("main").to_selection(),
     );
 }
+
+#[test]
+fn add_type_annotations_uses_internal_name_for_same_package() {
+    let src = "
+import thepackage/internal
+
+pub fn main() {
+  internal.Constructor
+}
+";
+
+    assert_code_action!(
+        ADD_ANNOTATION,
+        TestProject::for_source(src)
+            .add_module(
+                "thepackage/internal",
+                "
+pub type Internal { Constructor }
+"
+            )
+            .add_module(
+                "thepackage/external",
+                "
+import thepackage/internal
+
+pub type External = internal.Internal
+"
+            ),
+        find_position_of("main").to_selection(),
+    );
+}

compiler-core/src/language_server/tests/snapshots/gleam_core__language_server__tests__action__add_type_annotations_uses_internal_name_for_same_package.snap

@@ -0,0 +1,21 @@
+---
+source: compiler-core/src/language_server/tests/action.rs
+expression: "\nimport thepackage/internal\n\npub fn main() {\n  internal.Constructor\n}\n"
+---
+----- BEFORE ACTION
+
+import thepackage/internal
+
+pub fn main() {
+       ↑       
+  internal.Constructor
+}
+
+
+----- AFTER ACTION
+
+import thepackage/internal
+
+pub fn main() -> internal.Internal {
+  internal.Constructor
+}