Reference docs generator

tools/gendocs.php

@@ -0,0 +1,145 @@
+<?php
+require __DIR__ . '/../vendor/autoload.php';
+
+use GraphQL\Utils\Utils;
+
+$outputFile = __DIR__  . '/../docs/reference.md';
+
+$entries = [
+    \GraphQL\GraphQL::class,
+    \GraphQL\Type\Definition\Type::class,
+    \GraphQL\Type\SchemaConfig::class,
+    \GraphQL\Type\Schema::class,
+    \GraphQL\Language\Parser::class,
+    \GraphQL\Language\Printer::class,
+    \GraphQL\Language\Visitor::class,
+    \GraphQL\Language\AST\NodeKind::class => ['constants' => true],
+    \GraphQL\Executor\Executor::class,
+    \GraphQL\Executor\ExecutionResult::class,
+    \GraphQL\Executor\Promise\PromiseAdapter::class,
+    \GraphQL\Type\Definition\ResolveInfo::class,
+    \GraphQL\Validator\DocumentValidator::class,
+    \GraphQL\Error\Error::class => ['constants' => true, 'methods' => true, 'props' => true],
+    \GraphQL\Error\Warning::class => ['constants' => true, 'methods' => true],
+    \GraphQL\Error\ClientAware::class,
+    \GraphQL\Error\Debug::class => ['constants' => true],
+    \GraphQL\Error\FormattedError::class,
+    \GraphQL\Server\StandardServer::class,
+    \GraphQL\Server\ServerConfig::class,
+    \GraphQL\Server\Helper::class,
+    \GraphQL\Server\OperationParams::class
+];
+
+function renderClassMethod(ReflectionMethod $method) {
+    $args = Utils::map($method->getParameters(), function(ReflectionParameter $p) {
+        $type = ltrim($p->getType() . " ");
+        $def = $type . '$' . $p->getName();
+
+        if ($p->isDefaultValueAvailable()) {
+            $val = $p->isDefaultValueConstant() ? $p->getDefaultValueConstantName() : $p->getDefaultValue();
+            $def .= " = " . (is_array($val) ? '[]' : Utils::printSafe($val));
+        }
+
+        return $def;
+    });
+    $argsStr = implode(", ", $args);
+    if (strlen($argsStr) >= 80) {
+        $argsStr = "\n    " . implode(",\n    ", $args) . "\n";
+    }
+    $def = "function {$method->getName()}($argsStr)";
+    $def = $method->isStatic() ? "static $def" : $def;
+    $docBlock = unpadDocblock($method->getDocComment());
+
+    return <<<TEMPLATE
+```php
+{$docBlock}
+{$def}
+```
+TEMPLATE;
+}
+
+function renderConstant($value, $name) {
+    return "const $name = " . Utils::printSafe($value) . ";";
+}
+
+function renderProp(ReflectionProperty $prop) {
+    $signature = implode(" ", Reflection::getModifierNames($prop->getModifiers())) . ' $' . $prop->getName() . ';';
+    return unpadDocblock($prop->getDocComment()) . "\n" . $signature;
+}
+
+function renderClass(ReflectionClass $class, $options) {
+    $classDocs = unwrapDocblock(unpadDocblock($class->getDocComment()));
+    $content = '';
+    $label = $class->isInterface() ? 'Interface' : 'Class';
+
+    if (!empty($options['constants'])) {
+        $constants = $class->getConstants();
+        $constants = Utils::map($constants, 'renderConstant');
+        if (!empty($constants)) {
+            $constants = "```php\n" . implode("\n", $constants) . "\n```";
+            $content .= "**$label Constants:** \n$constants\n\n";
+        }
+    }
+
+    if (!empty($options['props'])) {
+        $props = $class->getProperties(ReflectionProperty::IS_PUBLIC);
+        $props = Utils::filter($props, 'isApi');
+        if (!empty($props)) {
+            $props = Utils::map($props, 'renderProp');
+            $props = "```php\n" . implode("\n\n", $props) . "\n```";
+            $content .= "**$label Props:** \n$props\n\n";
+        }
+    }
+
+    if (!empty($options['methods'])) {
+        $methods = $class->getMethods(ReflectionMethod::IS_PUBLIC);
+        $methods = Utils::filter($methods, 'isApi');
+        if (!empty($methods)) {
+            $renderedMethods = Utils::map($methods, 'renderClassMethod');
+            $renderedMethods = implode("\n\n", $renderedMethods);
+            $content .= "**$label Methods:** \n{$renderedMethods}\n";
+        }
+    }
+
+    return <<<TEMPLATE
+# {$class->getName()}
+{$classDocs}
+
+$content
+TEMPLATE;
+}
+
+function unwrapDocblock($docBlock, $stripAnnotations = true) {
+    $content = preg_replace('~([\r\n]) \* (.*)~i', '$1$2', $docBlock); // strip *
+    $content = preg_replace('~([\r\n])[\* ]+([\r\n])~i', '$1$2', $content); // strip single-liner *
+    $content = substr($content, 3); // strip leading /**
+    $content = substr($content, 0, -2); // strip trailing */
+    if ($stripAnnotations) {
+        $content = preg_replace('~([\r\n])@.*([\r\n])~i', '$1', $content); // strip annotations
+    }
+    return trim($content);
+}
+
+function unpadDocblock($docBlock) {
+    $lines = explode("\n", $docBlock);
+    $lines = \GraphQL\Utils\Utils::map($lines, function($line) {
+        return ' ' . trim($line);
+    });
+    return trim(implode("\n", $lines));
+}
+
+function isApi($entry) {
+    /** @var ReflectionProperty|ReflectionMethod $entry */
+    $isApi = preg_match('~[\r\n ]+\* @api~', $entry->getDocComment());
+    return $isApi;
+}
+
+file_put_contents($outputFile, '');
+
+foreach ($entries as $className => $options) {
+    $className = is_int($className) ? $options : $className;
+    $options = is_array($options) ? $options : ['methods' => true, 'props' => true];
+
+    $rendered = renderClass(new ReflectionClass($className), $options);
+    file_put_contents($outputFile, $rendered, FILE_APPEND);
+}