[jira] [Commented] (SLING-9479) GraphQL fetcher comments convert to headings in GraphiQL docs

[Bertrand Delacretaz (Jira)]

    [ 
https://issues.apache.org/jira/browse/SLING-9479?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17123629#comment-17123629
 ] 

Bertrand Delacretaz commented on SLING-9479:
--------------------------------------------

I dug deeper into this and it looks like an empty comment line after our 
{{fetch:}} definitions hides these from the field description, while keeping 
the {{fetch:}} definition attached to the field.

I tried that in [commit 
806ab95|https://github.com/apache/sling-org-apache-sling-graphql-core/commit/806ab952285fba2b58d98adfb3dd912c55784a95]
 and made similar changes to the [demo website 
code|https://github.com/apache/sling-samples/commit/cf34d2ab485b478653773367376aae0d1431c6ab]
 and the results look good, {{fetch:}} comments are gone from the field 
descriptions.

This leads to comments like these in schemas:

{code}
type SomeType { 
    path: String
    resourceType: String

    ## fetch:test/digest/md5 path
    #
    pathMD5: String

    ## fetch:test/digest/sha-256 path
    #
    # SHA256 digest of the path
    pathSHA256: String
...
{code}



I think the Absolute Truth comes from executing a query such as

{code}
{
  __schema {
    types {
        name
        description,
        fields {
            name
            description
        }
    }
  }
}
{code}

which provides the descriptions as per the GraphQK spec. Trying that on the 
demo website I get the correct descriptions without the {{fetch:}} comments.

If we can confirm this I'd say we keep the {{## fetch:}} syntax as is and 
simply recommend adding an empty comment line after it. I should also add tests 
to the GraphQL core module to verify this behavior.

> GraphQL fetcher comments convert to headings in GraphiQL docs
> -------------------------------------------------------------
>
>                 Key: SLING-9479
>                 URL: https://issues.apache.org/jira/browse/SLING-9479
>             Project: Sling
>          Issue Type: Bug
>          Components: GraphQL
>            Reporter: Bertrand Delacretaz
>            Assignee: Bertrand Delacretaz
>            Priority: Minor
>
> The GraphQL core currently uses comments like this to map fields to 
> DataFetchers:
> {code}
> ## fetch:samples/seeAlso
> {code}
> A common tool to look at those schemas is GraphiQL, which converts such 
> comments to headings, considering them to be Markdown.
> We should switch to a less intrusive marker that converts nicely to Markdown.



--
This message was sent by Atlassian Jira
(v8.3.4#803005)