search

profusion / sgqlc

Simple GraphQL Client
https://sgqlc.readthedocs.io/
ISC License
513 stars 85 forks source link

Add docstrings to schema generated by sgqlc-codegen #122

Closed SuperSonicHub1 closed 3 years ago

SuperSonicHub1 commented 3 years ago

GraphQL has support for descriptions written in CommonMark that help to describe the many parts of a schema. Using said descriptions and a type's fields, I'm certain that it would be possible to create detailed Python docstrings that helps developers traverse a schema while writing a query. When using a JSON version of a GraphQL schema, the descriptions of types and fields can be found under the description key. I'm sure users would also find it useful to mark certain fields as deprecated via looking at the isDeprecated and deprecationReason keys.

barbieri commented 3 years ago

Hum, it's easy to do indeed. But should we?

In my mind the Python layer would be just a help to avoid typing the verbose json access, such as data['field']['otherField']... Still people would know and refer to the schema, usually APIs provide a nice website to learn how to use.

Another possible problem is the mismatch, with the descriptions and deprecationReason people often point to the items using the GraphQL naming schema, it wouldn't reflect to the actual Python names.

anyway, let me know. These are simple to add.

SuperSonicHub1 commented 3 years ago

Having to look to a website in order to remember what something does is distracting and lowers productivity, hence docstings and code editors displaying them while writing code.

I think most developers wouldn't find themselves confused when trying to cross the bridge between names in camelCase and snake_case, as most people using this library already know field names are converted. We could use regex to replace any camelCase with snake_case, but that could possibly be destructive.

If you can add docstring generation and it's really easy, please do so as soon as possible.

barbieri commented 3 years ago

ok, will try to do this week

SuperSonicHub1 commented 3 years ago

@barbieri Just wondering about how far you've gotten with this.

barbieri commented 3 years ago

no time yet :-(

SuperSonicHub1 commented 3 years ago

Has any progress been made yet?

Kyle Williams

On Mon, Feb 15, 2021 at 8:58 AM Gustavo Sverzut Barbieri notifications@github.com wrote:

no time yet :-(

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or unsubscribe.

barbieri commented 3 years ago

no time, thus no progress... likely just in April :-(