Exported package interface returns wrong documentation

[mine-tech-oficial]

I've been doing the PR at #3669 and I noticed that when Gleam will export the package interface JSON, it returns the documentations with an extra newline. I've then tested on the compiler without my changes and it still behaves like that. You can test this by adding the following prints to debug it:

for module in modules.iter() {
    println!("Compiled module: {}", module.name);
    for (name, type_) in module.ast.type_info.types.iter() {
        match type_.documentation.clone() {
            Some(docs) => println!(
                "Compiled type {}/{} has documentation of length {}",
                module.name,
                name,
                docs.len()
            ),
            None => println!(
                "Compiled type {}/{} has no documentation",
                module.name, name
            ),
        }
    }
}

for module in loaded.cached.iter() {
    println!("Cached module: {}", module.name);
    for (name, type_) in module.types.iter() {
        match type_.documentation.clone() {
            Some(docs) => println!(
                "Cached type {}/{} has documentation of length {}",
                module.name,
                name,
                docs.len()
            ),
            None => println!("Cached type {}/{} has no documentation", module.name, name),
        }
    } 
}

at the end of the package_compiler.compile function and .map(|(name, info)| debug_module(name, info)) right before the .collect() in the package_interface.from_package function. Also make sure to define the following function in the package_interface module:

pub fn debug_module(name: EcoString, info: ModuleInterface) -> (EcoString, ModuleInterface) {
    info.types.iter().for_each(|(type_name, type_)| {
        match type_.documentation.clone() {
            Some(docs) => println!(
                "Exported type {}/{} has documentation of length {}",
                name,
                type_name,
                docs.len(),
            ),
            None => println!("Exported type {}/{} has no documentation", name, type_name),
        }
    });
    (name, info)
}

I believe the problem is with the Package::attach_doc_and_module_comments" in the build` module, although I'm not sure.

[lpil]

Could you give an example of some code and the documentation it provides please. Thank you

[mine-tech-oficial]

Actually, a little correction, when Gleam first creates the documentation, it seems that it appends a extra newline to the text, which is later removed on the attach_doc_and_module_comments function when it rebuilds the documentation. As such the documentation in the package export is correct, while before the function is called the documentation has a extra newline. I used the following code to test it:

import gleam/io

/// A person role inside a school
/// 
pub type SchoolPerson {
  Teacher(name: String, subject: String)
  Student(name: String)
}

/// A school type
pub type SchoolType {
  School(name: String, people: List(SchoolPerson))
  University(name: String, people: List(SchoolPerson))
}

pub fn main() {
  let teacher = Teacher("Mr Schofield", "Physics")
  let student = Student("Koushiar")

  io.debug(teacher.name)
  io.debug(student.name)
}

In the debug code above, I just modified the message to also include the documentation itself, and here is the output:

Compiled type export_test/SchoolPerson has following documentation (33): " A person role inside a school\n \n"
Compiled type export_test/SchoolType has following documentation (15): " A school type\n"
Exported type export_test/SchoolType has following documentation (14): " A school type"
Exported type export_test/SchoolPerson has following documentation (32): " A person role inside a school\n "

[lpil]

Why is it that the new lines are different each time it is printed?

[mine-tech-oficial]

See, that's the thing I couldn't work out exactly. What I believe is that the implementation for finding documentation in the analyze function and in the attach_doc_and_module_comments are slightly different, resulting in the analyze function (the line where it's written Compiled type...) appending an extra newline

[lpil]

The newline at the end is correct. UNIX says text lines must end with a newline.

[mine-tech-oficial]

Upon further inspection, I believe it isn't the attach_doc_and_module_comments implementation which returns the text without a newline, although I couldn't locate the place which removes the newline. In such case where there should be an newline at the end, wherever the newline is getting removed should be fixed, right?

[lpil]

I'm not sure it matter that much to be honest. Did you uncover some problem caused by it?

[mine-tech-oficial]

To be fair, just some differences, nothing more.

[lpil]

Let's close this for now then and reopen when we find it surfacing as a problem. Thank you