Typescript Generate Doc

[eMerzh]

Hello 👋

I know it's probably unconventional, and maybe the code looks not very nice (it's my first time in rust 😅 please be friendly 😬)

but I thought others would like this,

The idea is to have the documentation directly in TS while using your IDE...

I know there's already this kind of feature with the LSP, but here it's supposed to work with ts fields.

Example:

i'm willing to change things if necessary, but as a noob i might need some guidance 😅

[captbaritone]

Hey @eMerzh thanks for exploring this idea! I kinda love it! But I do worry that it may be prohibitively verbose for use internally. At the very least I think this should be an option. I'll start some discussions internally to gauge the viability of us using this. In the mean time, some TODOs for you, which you can work on now, or wait to see how likely this is to land:

1. Run Rust tests and update fixtures. The test failures should show a message explaining how to update the fixtures automatically
2. Implement this for Flow as well as TypeScript
3. Add a FeatureFlag for this and make the output conditional based on the feature flag

[captbaritone]

Another concern we'll need to address: Flow types are generated inside Flow comments, which can't have block comments nested within them. I'll see if there's a workaround here.

[captbaritone]

Another item to add to your test plan: Run the compiler in --watch mode and then modify just a field description and ensure that artifacts which include that field are correctly updated. It's possible that we do some clever short circuiting somewhere in the compiler that involves ignoring descriptions.

[eMerzh]

great thanks 🙌 ... i've added the TODO in the pr comment, I'll try to update that and look for help if needed :)

let me know if you have more info about your internal decisions ;-)

question: feature flag enabled by default?

[captbaritone]

We don't have any hard blockers internally, but I don't have a known solution to working around the Flow comment blocks. Maybe we need a separate feature flag to disable Flow comment blocks, and this feature flag would require that the other feature flag be enabled?

Let's disable the feature flag by default for now. We can always invert later.

[eMerzh]

@captbaritone i've added the flag, and fix the failing thing in tests (seems to have no outdated fixtures at this point? 🤔 ) but i have no idea how this could plays out with flow... as i'm not really using it 😬

AFAIK, inline // in those blocks won't be picked up by the IDE (at least vscode) so it's kinda useless ....

[eMerzh]

@captbaritone sorry for the ping.... but is there something waiting for me?

[captbaritone]

To enable this for tests you'll need to enable the feature flag here: https://github.com/facebook/relay/blob/3b9f90a2e1f4f1b4c9b0aa2a7597db48cb6be19f/compiler/crates/relay-typegen/tests/generate_typescript/mod.rs#L80

[captbaritone]

Looks like we'll also need to rebase.

[captbaritone]

I've asked internally about dealing with the Flow comments.

Can you add some tests to see what happens with various types of descriptions? Specifically things like long lines and line breaks.

Instructions for handling fixture tests can be fond here: https://github.com/facebook/relay/blob/main/.github/CONTRIBUTING.md

[eMerzh]

awesome that this is going further 🚀 ... i was wondering if it was forgotten 😬 ...

i've fix the remarks i think, except the tests, i'll check your link and do that :)

[eMerzh]

@captbaritone i've added a fixture, but of course, enabling the doc add it to a few other files... let me know if i missed anything :)

[eMerzh]

@captbaritone let me know if I missed something :)

[captbaritone]

I think we need a story for Flow here. I'm looking internally to see if maybe we can just drop the flow comment syntax.

[eMerzh]

hello :)

just rebased it ... and i take the oportunity to do a tiny bump @captbaritone 😬

[tobias-tengler]

Super excited about this change - especially the deprecation part. @eMerzh would you mind also adding the @deprecated JSDoc for deprecated arguments, input fields and enum values? Especially input fields would be pretty valuable, since you don't get any editor / lint feedback at the moment, even if an input field is deprecated in the schema.

[eMerzh]

hey @tobias-tengler glad i see some activity here :)

i'll see what i can do 😬 :)

[eMerzh]

@tobias-tengler & @captbaritone i think it's better now :)

Struggled a bit to find my way to parse the doc for inputs but, finally found it :)

[eMerzh]

hello here :)

notice it was conflicting, so i rebased .... but i also noticed that i reached the second page of pr 😱 like this is reaching the 🕳️ ...

if i can do something to help, let me know :)

[eMerzh]

@captbaritone sorry again for the ping ... rebased once again, is there something bloking? would love to have that in :)

[eMerzh]

hey 👋 monthly bump. didn't rebased yet because i'm not sure it's worth doing ATM , but i'll happilly do it if anyone is willing to have a look