[language-plugin] Add documentation.

Author: alloy

Diff for: packages/relay-compiler/language/RelayLanguagePluginInterface.js

@@ -16,60 +16,231 @@ const RelayConcreteNode = require('RelayConcreteNode');
 
 import type {IRTransform, Root, Fragment} from 'graphql-compiler';
 
+/**
+ * A language plugin allows relay-compiler to both read and write files for any
+ * language.
+ *
+ * When reading, the plugin is expected to parse and return GraphQL tags; and
+ * when writing the plugin is responsible for generating type information about
+ * the GraphQL selections made as well as generating the contents of the
+ * artifact file.
+ *
+ * This interface describes the details relay-compiler requires to be able to
+ * use the plugin. The plugin is expected to have as its main default export a
+ * function that returns an object conforming to this interface.
+ */
+export type PluginInterface = {
+  inputExtensions: string[],
+  outputExtension: string,
+  findGraphQLTags: GraphQLTagFinder,
+  formatModule: FormatModule,
+  typeGenerator: TypeGenerator,
+};
+
 export type GraphQLTag = {
-  keyName: ?string,
+  /**
+   * Should hold the string content of the `graphql` tagged template literal,
+   * which is either an operation or fragment.
+   *
+   * @example
+   *
+   *  grapqhl`query MyQuery { … }`
+   *  grapqhl`fragment MyFragment on MyType { … }`
+   */
   template: string,
+
+  /**
+   * In the case this tag was part of a fragment container and it used a node
+   * map as fragment spec, rather than a single tagged node, this should hold
+   * the prop key to which the node is assigned.
+   *
+   * @example
+   *
+   *  createFragmentContainer(
+   *    MyComponent,
+   *    {
+   *      keyName: graphql`fragment MyComponent_keyName { … }`
+   *    }
+   *  )
+   *
+   */
+  keyName: ?string,
+
+  /**
+   * The location in the source file that the tag is placed at.
+   */
   sourceLocationOffset: {
-    /* TODO: Is this also expected to yse 1-based index? */
+    /**
+     * The line in the source file that the tag is placed on.
+     *
+     * Lines use 1-based indexing.
+     */
     line: number,
-    /* Should use 1-based index */
+
+    /**
+     * The column in the source file that the tag starts on.
+     *
+     * Columns use 1-based indexing.
+     */
     column: number,
   },
 };
 
+/**
+ * This function is responsible for extracting `GraphQLTag` objects from source
+ * files.
+ *
+ * @param  {string} text       The source file contents.
+ * @param  {string} filePath   The path to the source file on disk.
+ * @return {Array<GraphQLTag>} All extracted `GraphQLTag` objects.
+ *
+ * @see {@link javascript/FindGraphQLTags.js}
+ */
 export type GraphQLTagFinder = (
   text: string,
   filePath: string,
 ) => Array<GraphQLTag>;
 
 /**
- * Generate a module for the given document name/text.
+ * The function that is responsible for generating the contents of the artifact
+ * file.
+ *
+ * @see {@link javascript/formatGeneratedModule.js}
  */
 export type FormatModule = ({|
+  /**
+   * The filename of the module.
+   */
   moduleName: string,
+
+  /**
+   * The type of artifact that this module represents.
+   *
+   * @todo Document when this can be `empty`.
+   */
   documentType:
     | typeof RelayConcreteNode.FRAGMENT
     | typeof RelayConcreteNode.REQUEST
     | typeof RelayConcreteNode.BATCH_REQUEST
     | null,
+
+  /**
+   * The actual document that this module represents.
+   */
   docText: ?string,
+
+  /**
+   * The IR for the document that this module represents.
+   */
   concreteText: string,
+
+  /**
+   * The type information generated for the GraphQL selections made.
+   */
   typeText: string,
-  hash: ?string,
-  devOnlyAssignments: ?string,
+
+  /**
+   * The name of the relay-runtime module being used.
+   */
   relayRuntimeModule: string,
+
+  /**
+   * A hash of the concrete node including the query text.
+   *
+   * @todo Document how this is different from `sourceHash`.
+   */
+  hash: ?string,
+
+  /**
+   * A hash of the document, which is used by relay-compiler to know if it needs
+   * to write a new version of the artifact.
+   *
+   * @todo Is this correct? And document how this is different from `hash`.
+   */
   sourceHash: string,
+
+  /**
+   * @todo Document this.
+   */
+  devOnlyAssignments: ?string,
 |}) => string;
 
+/**
+ * The options that will be passed to the `generate` function of your plugin’s
+ * type generator.
+ */
 export type TypeGeneratorOptions = {|
+  /**
+   * A map of custom scalars to scalars that the plugin knows about and emits
+   * tpye information for.
+   *
+   * @example
+   *
+   *  // The URL custom scalar is essentially a string and should be treated as
+   *  // such by the language’s type system.
+   *  { URL: 'String' }
+   */
   +customScalars: {[type: string]: string},
-  +useHaste: boolean,
-  +enumsHasteModule: ?string,
+
+  /**
+   * Lists all other fragments relay-compiler knows about. Use this to know when
+   * to import/reference other artifacts.
+   */
   +existingFragmentNames: Set<string>,
-  +inputFieldWhiteList: $ReadOnlyArray<string>,
+
+  /**
+   * The name of the relay-runtime module.
+   *
+   * This defaults to `relay-runtime`.
+   */
   +relayRuntimeModule: string,
+
+  /**
+   * Whether or not relay-compiler will store artifacts next to the module that
+   * they originate from or all together in a single directory.
+   *
+   * Storing all artifacts in a single directory makes it easy to import and
+   * reference fragments defined in other artifacts without needing to use the
+   * Haste module system.
+   *
+   * This defaults to `false`.
+   */
   +useSingleArtifactDirectory: boolean,
+
+  /**
+   * @todo Document this.
+   */
+  +inputFieldWhiteList: $ReadOnlyArray<string>,
+
+  /**
+   * Whether or not the Haste module system is being used. This will currently
+   * always be `false` for OSS users.
+   */
+  +useHaste: boolean,
+
+  /**
+   * @todo Document this.
+   */
+  +enumsHasteModule: ?string,
 |};
 
+/**
+ * This object should hold the implementation required to generate types for the
+ * GraphQL selections made.
+ *
+ * @see {@link javascript/RelayFlowGenerator.js}
+ */
 export type TypeGenerator = {
+  /**
+   * Transforms that should be applied to the intermediate representation of the
+   * GraphQL document before passing to the `generate` function.
+   */
   transforms: Array<IRTransform>,
-  generate: (node: Root | Fragment, options: TypeGeneratorOptions) => string,
-};
 
-export type PluginInterface = {
-  inputExtensions: string[],
-  outputExtension: string,
-  findGraphQLTags: GraphQLTagFinder,
-  formatModule: FormatModule,
-  typeGenerator: TypeGenerator,
+  /**
+   * Given GraphQL document IR, this function should generate type information
+   * for e.g. the selections made. It can, however, also generate any other
+   * content such as importing other files, including other artifacts.
+   */
+  generate: (node: Root | Fragment, options: TypeGeneratorOptions) => string,
 };