Show documentation for each variant when a field is shared across variants

Author: GearsDatapacks

compiler-core/src/analyse.rs

@@ -38,7 +38,7 @@ use crate::{
     warning::TypeWarningEmitter,
 };
 use camino::Utf8PathBuf;
-use ecow::EcoString;
+use ecow::{EcoString, eco_format};
 use hexpm::version::Version;
 use itertools::Itertools;
 use name::{check_argument_names, check_name_case};
@@ -1979,7 +1979,20 @@ fn get_compatible_record_fields(constructors: &[TypeValueConstructor]) -> Vec<Re
             None => continue 'next_argument,
         };
 
-        let mut documentation = first_parameter.documentation.clone();
+        let mut documentation = if constructors.len() == 1 {
+            // If there is only one constructor, we simply show the documentation
+            // for the field.
+            first_parameter.documentation.clone()
+        } else if let Some(field_documentation) = &first_parameter.documentation {
+            // If there are multiple constructors, we show the documentation of
+            // this field for each of the variants.
+            Some(eco_format!("## {}\n\n{}", first.name, field_documentation))
+        } else {
+            // If there is no documentation on the field of the first constructor,
+            // we leave it as `None` until we find a field which does have
+            // documentation.
+            None
+        };
 
         // Check each variant to see if they have an field in the same position
         // with the same label and the same type
@@ -2004,9 +2017,20 @@ fn get_compatible_record_fields(constructors: &[TypeValueConstructor]) -> Vec<Re
                 continue 'next_argument;
             }
 
-            // If there is more than one variant, we can't show documentation
-            // as we do not know which field it is.
-            documentation = None;
+            if let Some(field_documentation) = &parameter.documentation {
+                let field_documentation =
+                    eco_format!("## {}\n\n{}", constructor.name, field_documentation);
+
+                match &mut documentation {
+                    None => {
+                        documentation = Some(field_documentation);
+                    }
+                    Some(documentation) => {
+                        documentation.push('\n');
+                        documentation.push_str(&field_documentation);
+                    }
+                }
+            }
         }
 
         // The previous loop did not find any incompatible fields in the other

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

@@ -1780,7 +1780,7 @@ pub type Wibble {
     wibble: Int
   )
   Wobble(
-    /// This won't show up because we don't know which wibble field it is
+    /// Here's some documentation explaining a field of Wobble
     wibble: Int
   )
 }

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

@@ -1,14 +1,14 @@
 ---
 source: compiler-core/src/language_server/tests/hover.rs
-expression: "\npub type Wibble {\n  Wibble(\n    /// This is some documentation about the wibble field.\n    wibble: Int\n  )\n  Wobble(\n    /// This won't show up because we don't know which wibble field it is\n    wibble: Int\n  )\n}\n\npub fn wibble(w: Wibble) {\n  w.wibble\n}\n"
+expression: "\npub type Wibble {\n  Wibble(\n    /// This is some documentation about the wibble field.\n    wibble: Int\n  )\n  Wobble(\n    /// Here's some documentation explaining a field of Wobble\n    wibble: Int\n  )\n}\n\npub fn wibble(w: Wibble) {\n  w.wibble\n}\n"
 ---
 pub type Wibble {
   Wibble(
     /// This is some documentation about the wibble field.
     wibble: Int
   )
   Wobble(
-    /// This won't show up because we don't know which wibble field it is
+    /// Here's some documentation explaining a field of Wobble
     wibble: Int
   )
 }
@@ -22,6 +22,6 @@ pub fn wibble(w: Wibble) {
 ----- Hover content -----
 Scalar(
     String(
-        "```gleam\nInt\n```\n",
+        "```gleam\nInt\n```\n## Wibble\n\n This is some documentation about the wibble field.\n\n## Wobble\n\n Here's some documentation explaining a field of Wobble\n",
     ),
 )