kitsonk
commented
2 years ago Thanks for the feedback.
The reasoning behind the change is that scanning 1000 line of code for information isn't very useful, especially when trying to use a 3rd party module. Having a documentation first view makes things easier for people to understand when trying to consume 3rd party code. Not everyone has a compiler in their head, and even if they had one, reading code isn't the most effective way to figure out how to deal with it.
We make sure that when you are clicking on a stack trace, you get to the specific line, for example [https://deno.land/x/cloudseed@v0.0.20/graphql/generate.ts:37:12][https://deno.land/x/cloudseed@v0.0.20/graphql/generate.ts:37:12]. Outside of that, intelligent editors which leverage the Deno language service have the ability to go to source on third party modules and have them available in the editor, which is a much better way to view source code.
Also there is a lot of precedent for "documentation first" views of code. Both GoLang and docs.rs provide a documentation first view of the code.
If you need a richer source view, then deno.land/x is never going to meet your needs and it would be a lot better to browse the code in the source control website that publishes it. GitHub is designed for viewing code. deno.land/x was designed to provide information about 3rd party modules that can be consumed by Deno. The documentation view fits that better.
We realise a lot of 3rd party packages aren't taking advantage of the rich documentation, partly because there hasn't been anything there to see. We will add a section to the manual on how to best ensure your JSDoc works well. In the specific example you provided, in generate.ts, if you were to add the @module tag to the JSDoc block, you would get a lot better documentation for that module on the site:
/**
* VERY OPINIONATED SCRIPT, NOT DESIGNED FOR GENERAL USE OUTSIDE OF CLOUDSEED GRAPHQL TYPES GENERATION
* Runs npm @graphql-codegen to generate graphql bindings from
* a running graphql server with the default settings:
* - src/graphql/queries.graphql (contain all your queries)
* - src/graphql/generated/types (generated)
* This is used in multiple repositories, so capture in a deno script
*
* @module
*/We know that it will take a while for module authors to adjust, but defaulting to a source view will sadly, not politely force people to improve their documentation.
dionjwa
I loved being able to click on a link and look directly at code.
But with the new update, there is a structured docs type page, with examples how to import.
E.g. for my own modules: https://deno.land/x/cloudseed@v0.0.20/graphql/generate.ts
One of the awesome things about deno is that errors give URLs you can click on and directly see the code in question. The developer process is phenomenal.
The new structured view I can see as helpful to some people, but it would be great to be opt-in, or maybe a side bar, but having the code itself front and center on clicking a link is IMO ideal for most of the time most people visit (obv I am biased and have zero data to back this up, just a hunch).
Right now, I have to click an extra button to get to the code. It sounds like not much, but when developing, debugging, understanding, it's an annoying extra click over and over.
BTW this is a great set of tools, and I am a huge fan, if "fan" is the right word. Keep up the awesomeness!!!!