captbaritone
Support for `@` in descriptions
According to the docs, @ in description comments makes the comment get truncated
Depending upon your version of TypeScript, descriptions with a @ symbol in their text, for example a GitHub handle, may get truncated. To avoid this, you can wrap the tag in quotes or backticks.
/** This comment was added by `@captbaritone`. */
This limitation makes it impossible to put GraphQL example code in documentation comments.
For example, take the native @semanticNonNull that grats ships with. This is impossible to declare using grats:
import {Int} from 'grats';
/**
* Indicates that a position is semantically non null: it is only null if there is a matching error in the `errors` array.
* In all other cases, the position is non-null.
*
* Tools doing code generation may use this information to generate the position as non-null if field errors are handled out of band:
*
* ```graphql
* type User {
* # email is semantically non-null and can be generated as non-null by error-handling clients.
* email: String @semanticNonNull
* }
* ```
*
* The `levels` argument indicates what levels are semantically non null in case of lists:
*
* ```graphql
* type User {
* # friends is semantically non null
* friends: [User] @semanticNonNull # same as @semanticNonNull(levels: [0])
*
* # every friends[k] is semantically non null
* friends: [User] @semanticNonNull(levels: [1])
*
* # friends as well as every friends[k] is semantically non null
* friends: [User] @semanticNonNull(levels: [0, 1])
* }
* ```
*
* `levels` are zero indexed.
* Passing a negative level or a level greater than the list dimension is an error.
* @gqlDirective on FIELD_DEFINITION
*/
export function semanticNonNull({ levels = [0] }: { levels: Int[] }) {}
Produces a truncated description:
"""
Indicates that a position is semantically non null: it is only null if there is a matching error in the `errors` array.
In all other cases, the position is non-null.
Tools doing code generation may use this information to generate the position as non-null if field errors are handled out of band:
```graphql
type User {
# email is semantically non-null and can be generated as non-null by error-handling clients.
email: String
"""
directive @semanticNonNull(levels: [Int!]! = [0]) on FIELD_DEFINITION
Afaik there is currently no work around in grats to produce the desired output.
It looks like TypeScript supports escaping @ with \@.
https://www.typescriptlang.org/play/?#code/PQKhCgAIUgJBTANog9pAOgAQC4At4BO8UMJkZJw42AngA7yQBiKaAvJAEQBCAhgZyA
I think Grats should try to do the same. Let me see if I can figure out how.
Next step here will be to poke through TypeScript code to see exactly where/how this happens to see if there's a public function we can reuse or if we can at least be sure we are matching their implementation.