style(JSDoc): document private functions with @internal tag

Closes #2183

Author: Enda Phelan

src/__tests__/starWarsData.js

@@ -122,6 +122,8 @@ function getCharacter(id) {
 
 /**
  * Allows us to query for a character's friends.
+ * 
+ * @internal
  */
 export function getFriends(character: Character): Array<Promise<Character>> {
   // Notice that GraphQL accepts Arrays of Promises.
@@ -130,6 +132,8 @@ export function getFriends(character: Character): Array<Promise<Character>> {
 
 /**
  * Allows us to fetch the undisputed hero of the Star Wars trilogy, R2-D2.
+ * 
+ * @internal
  */
 export function getHero(episode: number): Character {
   if (episode === 5) {
@@ -142,13 +146,17 @@ export function getHero(episode: number): Character {
 
 /**
  * Allows us to query for the human with the given id.
+ * 
+ * @internal
  */
 export function getHuman(id: string): Human {
   return humanData[id];
 }
 
 /**
  * Allows us to query for the droid with the given id.
+ * 
+ * @internal
  */
 export function getDroid(id: string): Droid {
   return droidData[id];

src/execution/execute.js

@@ -244,6 +244,8 @@ function buildResponse(
 /**
  * Essential assertions before executing to provide developer feedback for
  * improper use of the GraphQL library.
+ * 
+ * @internal
  */
 export function assertValidExecutionArguments(
   schema: GraphQLSchema,
@@ -267,6 +269,8 @@ export function assertValidExecutionArguments(
  * execute, which we will pass throughout the other execution methods.
  *
  * Throws a GraphQLError if a valid execution context cannot be created.
+ * 
+ * @internal
  */
 export function buildExecutionContext(
   schema: GraphQLSchema,
@@ -465,6 +469,8 @@ function executeFields(
  * CollectFields requires the "runtime type" of an object. For a field which
  * returns an Interface or Union type, the "runtime type" will be the actual
  * Object type returned by that field.
+ * 
+ * @internal
  */
 export function collectFields(
   exeContext: ExecutionContext,
@@ -641,6 +647,9 @@ function resolveField(
   );
 }
 
+/**
+ * @internal
+ */
 export function buildResolveInfo(
   exeContext: ExecutionContext,
   fieldDef: GraphQLField<mixed, mixed>,
@@ -664,8 +673,12 @@ export function buildResolveInfo(
   };
 }
 
-// Isolates the "ReturnOrAbrupt" behavior to not de-opt the `resolveField`
-// function. Returns the result of resolveFn or the abrupt-return Error object.
+/**
+ * Isolates the "ReturnOrAbrupt" behavior to not de-opt the `resolveField`
+ * function. Returns the result of resolveFn or the abrupt-return Error object.
+ * 
+ * @internal
+ */
 export function resolveFieldValueOrError(
   exeContext: ExecutionContext,
   fieldDef: GraphQLField<mixed, mixed>,
@@ -1192,6 +1205,8 @@ export const defaultFieldResolver: GraphQLFieldResolver<
  * are allowed, like on a Union. __schema could get automatically
  * added to the query type, but that would require mutating type
  * definitions, which would cause issues.
+ * 
+ * @internal
  */
 export function getFieldDef(
   schema: GraphQLSchema,

src/execution/values.js

@@ -41,6 +41,8 @@ type CoercedVariableValues =
  * Note: The returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * 
+ * @internal
  */
 export function getVariableValues(
   schema: GraphQLSchema,
@@ -153,6 +155,8 @@ function coerceVariableValues(
  * Note: The returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * 
+ * @internal
  */
 export function getArgumentValues(
   def: GraphQLField<mixed, mixed> | GraphQLDirective,

src/jsutils/Path.js

@@ -7,6 +7,8 @@ export type Path = {|
 
 /**
  * Given a Path and a key, return a new Path containing the new key.
+ * 
+ * @internal
  */
 export function addPath(prev: $ReadOnly<Path> | void, key: string | number) {
   return { prev, key };

src/language/__tests__/parser-benchmark.js

@@ -6,6 +6,10 @@ import { kitchenSinkQuery } from '../../__fixtures__';
 
 export const name = 'Parse kitchen sink';
 export const count = 1000;
+
+/**
+ * @internal
+ */
 export function measure() {
   parse(kitchenSinkQuery);
 }

src/language/blockString.js

@@ -5,6 +5,8 @@
  * CoffeeScript's block string, Python's docstring trim or Ruby's strip_heredoc.
  *
  * This implements the GraphQL spec's BlockStringValue() static algorithm.
+ * 
+ * @internal
  */
 export function dedentBlockStringValue(rawString: string): string {
   // Expand a block string's raw value into independent lines.
@@ -30,8 +32,9 @@ export function dedentBlockStringValue(rawString: string): string {
   // Return a string of the lines joined with U+000A.
   return lines.join('\n');
 }
-
-// @internal
+/**
+ * @internal
+ */
 export function getBlockStringIndentation(
   lines: $ReadOnlyArray<string>,
 ): number {
@@ -71,6 +74,8 @@ function isBlank(str) {
  * Print a block string in the indented block form by adding a leading and
  * trailing blank line. However, if a block string starts with whitespace and is
  * a single-line, adding a leading blank line would strip that whitespace.
+ * 
+ * @internal
  */
 export function printBlockString(
   value: string,

src/language/lexer.js

@@ -93,7 +93,9 @@ export type Lexer<TOptions> = {
   ...
 };
 
-// @internal
+/**
+ * @internal
+ */
 export function isPunctuatorTokenKind(kind: TokenKindEnum) {
   return (
     kind === TokenKind.BANG ||

src/type/definition.js

@@ -822,6 +822,9 @@ function fieldsToFieldsConfig(fields) {
   }));
 }
 
+/**
+ * @internal
+ */
 export function argsToArgsConfig(
   args: $ReadOnlyArray<GraphQLArgument>,
 ): GraphQLFieldConfigArgumentMap {

src/utilities/__tests__/buildASTSchema-benchmark.js

@@ -10,6 +10,10 @@ const schemaAST = parse(bigSchemaSDL);
 
 export const name = 'Build Schema from AST';
 export const count = 10;
+
+/**
+ * @internal
+ */
 export function measure() {
   buildASTSchema(schemaAST, { assumeValid: true });
 }

src/utilities/__tests__/buildClientSchema-benchmark.js

@@ -6,6 +6,10 @@ import { bigSchemaIntrospectionResult } from '../../__fixtures__';
 
 export const name = 'Build Schema from Introspection';
 export const count = 10;
+
+/**
+ * @internal
+ */
 export function measure() {
   buildClientSchema(bigSchemaIntrospectionResult.data, { assumeValid: true });
 }

src/utilities/__tests__/introspectionFromSchema-benchmark.js

@@ -13,6 +13,10 @@ const schema = buildSchema(bigSchemaSDL, { assumeValid: true });
 
 export const name = 'Execute Introspection Query';
 export const count = 10;
+
+/**
+ * @internal 
+ */
 export function measure() {
   execute(schema, queryAST);
 }

src/validation/__tests__/harness.js

@@ -370,6 +370,9 @@ export const testSchema = new GraphQLSchema({
   ],
 });
 
+/**
+ * @internal
+ */
 export function expectValidationErrorsWithSchema(
   schema: GraphQLSchema,
   rule: ValidationRule,
@@ -380,10 +383,16 @@ export function expectValidationErrorsWithSchema(
   return expect(errors);
 }
 
+/**
+ * @internal
+ */
 export function expectValidationErrors(rule: ValidationRule, queryStr: string) {
   return expectValidationErrorsWithSchema(testSchema, rule, queryStr);
 }
 
+/**
+ * @internal
+ */
 export function expectSDLValidationErrors(
   schema: ?GraphQLSchema,
   rule: SDLValidationRule,

src/validation/__tests__/validateGQL-benchmark.js

@@ -13,6 +13,10 @@ const queryAST = parse(getIntrospectionQuery());
 
 export const name = 'Validate Introspection Query';
 export const count = 50;
+
+/**
+ * @internal
+ */
 export function measure() {
   validate(schema, queryAST);
 }

src/validation/__tests__/validateInvalidGQL-benchmark.js

@@ -24,6 +24,10 @@ const queryAST = parse(`
 
 export const name = 'Validate Invalid Query';
 export const count = 50;
+
+/**
+ * @internal
+ */
 export function measure() {
   validate(schema, queryAST);
 }

src/validation/__tests__/validateSDL-benchmark.js

@@ -10,6 +10,10 @@ const sdlAST = parse(bigSchemaSDL);
 
 export const name = 'Validate SDL Document';
 export const count = 10;
+
+/**
+ * @internal
+ */
 export function measure() {
   validateSDL(sdlAST);
 }

src/validation/validate.js

@@ -82,7 +82,9 @@ export function validate(
   return errors;
 }
 
-// @internal
+/**
+ * @internal
+ */
 export function validateSDL(
   documentAST: DocumentNode,
   schemaToExtend?: ?GraphQLSchema,