Predictable Doc Output Format for GraphQL

[webOS101]

This is more a feature request/future planning idea. Right now, the JSON output of a doc parsing run cannot (easily) be used with something like GraphQL because it requires a certain amount of predictability for querying. Because of the deeply nested nature of, for example, description elements, you can't produce a proper query against them. This same problem can apply against parameter types.

I'm not certain how to go about generating consistent and predictable output, but it seemed with the rise in popularity of GraphQL it was worth bringing up the issue to see if there were solutions (either from the documentation end or from the GraphQL end).

Does anyone have any thoughts on this?

[jaydenseric]

I'm not really following what the dilemma is. You can use interfaces for infinite nesting. Here's something thrown out there:

enum Kind {
  CLASS
  CONSTANT
  EVENT
  EXTERNAL
  FILE
  FUNCTION
  MEMBER
  MIXIN
  MODULE
  NAMESPACE
  TYPEDEF
}

enum Relationship {
  INSTANCE
  STATIC
  INNER
}

type Membership {
  memberOf: String!
  relationship: Relationship!
}

interface Member {
  kind: Kind!
  name: String!
  memberOf: String
  membership: Membership
  members: [Member!]
}

type Constant implements Member {
  kind: Kind!
  name: String!
  memberOf: String
  membership: Membership
  members: [Member!]
  type: String!
}

# Etc.

I would use the Relay Connections spec for paginating members though.

[webOS101]

I'll admit my GraphQL is a bit weak. My question would be how you would be able to pull down this deeply nested structure via GraphQL without hundreds of requests for a single description? GraphQL queries must be complete, as I understand it, so you can't just request 'as deep as necessary to get my data', you have to instead spell all that out. It could just be a limitation of the GraphQL interface I'm using, though (using Gatsby to create a documentation site).

[jaydenseric]

you can't just request 'as deep as necessary to get my data', you have to instead spell all that out

Hmm, you're right, I get your dilemma now! The way around it is have a decendants array on Member that has every nested descendant flattened into a list. With memberOf and a maybe a new namepath property on each, you can rebuild the nested structure from the array.

You might be interested how I constructed a system a bit like this for jsdoc-md, a lightweight alternative to documentation. Internally (see https://github.com/jaydenseric/jsdoc-md/blob/v1.5.0/lib/membersToMdAst.js#L34), it creates one array containing every member in the tree (or trees, if there are sibling top level members). Here is a snapshot of an outlined members array: https://github.com/jaydenseric/jsdoc-md/blob/v1.5.0/tap-snapshots/lib-outlineMembers.test.js-TAP.test.js#L9 (the JSON snapshot replaces the circular references with reference strings beginning with ~).