Multiline comments / descriptions

[willruggiano]

It would be nice if a line break (in TS comments) did not always manifest as a newline in the generated graphql schema. This is super nit picky obviously, but looks weird in e.g. graphiql.

For example, I would expect this to be a "single line" description:

/*
 * This is a really long description that takes up
 * multiple lines because maybe my editor or formatter
 * automatically split them up for me!
 * 
 * @gqlType
 */
type Foo = {
  ...
};

but the generated schema currently would be (note the newlines):

    description:
      "This is a really long description that takes up\nmultiple lines because maybe my editor or formatter\nautomatically split them up for me!",

vs a multi line description accomplished via an explicit empty line;

/*
 * This is a really long description that takes up
 * multiple lines because maybe my editor or formatter
 * automatically split up the lines on my behalf!
 *                                                     <-- explicit empty line
 * A new line!
 * 
 * @gqlType
 */
type Foo = {
  ...
};

[willruggiano]

I assume however that this is just a typescript / jsdoc limitation and there is in fact nothing that grats can do :/

[captbaritone]

The expectation in both GraphQL and TypeScript is that these descriptions are in Markdown. Line breaks in Markdown are not significant, so in theory we could collapse single line breaks to just spaces and still be ~correct. That said, I think that would require us to do some degree of pretty-printing somewhere. Also, multiple line breaks are significant in markdown (paragraph breaks) so we can't get rid of them all together.

Note that the main place these descriptions get surfaced are in the schema SDL. There the line breaks are preserved as line breaks, and I think it looks reasonable:

"""
This is a really long description that takes up
multiple lines because maybe my editor or formatter
automatically split them up for me!
"""
type Foo {
  name: String
}

Playground Link

In general I think the generated typescript schema file is not really intended to be read by humans. Maybe inspected by humans if they wish, or a place you could set a breakpoint, but not something I expect folks to be looking at on a regular basis. So I'm not that concerned about how elegant that code looks as long as it's debuggable and easy to reason about.

Does that make sense?

[willruggiano]

Yeah totally agreed on the generated typescript schema. I am talking about the graphql schema.

"""
This is a really long description that takes up
multiple lines because maybe my editor or formatter
automatically split them up for me!
"""
type Foo {
  name: String
}

looks weird in something like graphiql or ruru since they render the line breaks as is (same as if I'd written these descriptions by hand). Whereas what I'd like (caveat: nit pick) is this:

"""
This is a really long description that takes up multiple lines because maybe my editor or formatter automatically split them up for me!
"""
type Foo {
  name: String
}

All a single line.

[willruggiano]

and to your point about single line breaks (being insignificant) vs multiple line breaks (which are significant). To my point, I don't see a way of writing my comments such that they obey the laws of my editor / linter / formatter / whatever and allow me to craft multi paragraph descriptions without introducing arbitrary line breaks (due to wrapping) that are, according to markdown, insignificant