danog/endtoend-test-psl
1
0
Fork 0
mirror of https://github.com/danog/endtoend-test-psl.git synced 2025-01-23 05:41:21 +01:00
Code Issues Packages Projects Releases Wiki Activity

improve symbol links in documentation

Browse Source
This commit is contained in:
azjezz 2021-03-17 02:13:15 +01:00
parent 978de7b7a6
commit 96cf513172
3 changed files with 594 additions and 569 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1058
docs/README.md
View File

File diff suppressed because it is too large Load Diff

93
docs/documenter.php
View File

@ -93,41 +93,36 @@ function get_namespace_documentation(string $namespace): string
$lines[] = ''; $lines[] = '';
/** /**
* @param array{ * @param array<int, list<string>> $symbols
* 'constants' => list<string>,
* 'functions' => list<string>,
* 'interface' => list<string>,
* 'classes' => list<string>,
* 'traits' => list<string>,
* } $symbols
* @param 'constants'|'functions'|'interfaces'|'classes'|'traits' $type
* *
* @return list<string> * @return list<string>
*/ */
$generator = static function ( $generator = static function (
string $directory, string $directory,
array $symbols, array $symbols,
string $type int $type
): array { ): array {
$lines = []; $lines = [];
if (Iter\count($symbols[$type]) > 0) { if (Iter\count($symbols[$type]) > 0) {
$lines[] = Str\format('#### `%s`', Str\uppercase($type)); $lines[] = Str\format('#### `%s`', get_symbol_type_name($type));
$lines[] = ''; $lines[] = '';
foreach ($symbols[$type] as $function) { foreach ($symbols[$type] as $symbol) {
$short_name = Str\after_last($function, '\\'); $symbol_short_name = Str\after_last($symbol, '\\');
if ('constants' === $type) { if (Loader::TYPE_CONSTANTS === $type) {
$url = Str\format('%s%s%s.php', $directory, Filesystem\SEPARATOR, 'constants'); $symbol_file = Str\format('%s%s%s.php', $directory, Filesystem\SEPARATOR, 'constants');
} else { } else {
$url = Str\format('%s%s%s.php', $directory, Filesystem\SEPARATOR, $short_name); $symbol_file = Str\format('%s%s%s.php', $directory, Filesystem\SEPARATOR, $symbol_short_name);
} }
$symbol_file_contents = Filesystem\read_file(Filesystem\canonicalize(__DIR__ . '/' . $symbol_file));
$deprecation_notice = ''; $deprecation_notice = '';
if (Str\contains(Filesystem\read_file(Filesystem\canonicalize(__DIR__ . '/' . $url)), '@deprecated')) { if (Str\contains($symbol_file_contents, '@deprecated')) {
$deprecation_notice .= ' ( deprecated )'; $deprecation_notice .= ' ( deprecated )';
} }
$lines[] = Str\format('- [%s](%s)%s', $short_name, $url, $deprecation_notice); $definition_line = get_symbol_definition_line($symbol, $type);
$lines[] = Str\format('- [%s](%s#L%d)%s', $symbol_short_name, $symbol_file, $definition_line, $deprecation_notice);
} }
$lines[] = ''; $lines[] = '';
@ -141,11 +136,11 @@ function get_namespace_documentation(string $namespace): string
return Str\join(Vec\concat( return Str\join(Vec\concat(
$lines, $lines,
$generator($directory, $symbols, 'constants'), $generator($directory, $symbols, Loader::TYPE_CONSTANTS),
$generator($directory, $symbols, 'functions'), $generator($directory, $symbols, Loader::TYPE_FUNCTION),
$generator($directory, $symbols, 'interfaces'), $generator($directory, $symbols, Loader::TYPE_INTERFACE),
$generator($directory, $symbols, 'classes'), $generator($directory, $symbols, Loader::TYPE_CLASS),
$generator($directory, $symbols, 'traits'), $generator($directory, $symbols, Loader::TYPE_TRAIT),
[''] ['']
), "\n"); ), "\n");
} }
@ -153,13 +148,7 @@ function get_namespace_documentation(string $namespace): string
/** /**
* Return a shape contains all direct symbols in the given namespace. * Return a shape contains all direct symbols in the given namespace.
* *
* @return array{ * @return array<int, list<string>>
* 'constants' => list<string>,
* 'functions' => list<string>,
* 'interface' => list<string>,
* 'classes' => list<string>,
* 'traits' => list<string>,
* }
*/ */
function get_direct_namespace_symbols(string $namespace): array function get_direct_namespace_symbols(string $namespace): array
{ {
@ -179,11 +168,11 @@ function get_direct_namespace_symbols(string $namespace): array
); );
return [ return [
'constants' => $filter(Loader::CONSTANTS), Loader::TYPE_CONSTANTS => $filter(Loader::CONSTANTS),
'functions' => $filter(Loader::FUNCTIONS), Loader::TYPE_FUNCTION => $filter(Loader::FUNCTIONS),
'interfaces' => $filter(Loader::INTERFACES), Loader::TYPE_INTERFACE => $filter(Loader::INTERFACES),
'classes' => $filter(Loader::CLASSES), Loader::TYPE_CLASS => $filter(Loader::CLASSES),
'traits' => $filter(Loader::TRAITS), Loader::TYPE_TRAIT => $filter(Loader::TRAITS),
]; ];
} }
@ -222,3 +211,39 @@ function get_all_namespaces(): array
'Psl\Vec', 'Psl\Vec',
]; ];
} }
/**
* Return the name of the symbol type.
*/
function get_symbol_type_name(int $type): string {
switch ($type) {
case Loader::TYPE_CONSTANTS:
return 'Constants';
case Loader::TYPE_FUNCTION:
return 'Functions';
case Loader::TYPE_INTERFACE:
return 'Interfaces';
case Loader::TYPE_CLASS:
return 'Classes';
case Loader::TYPE_TRAIT:
return 'Traits';
}
}
/**
* Return the line where $symbol is defined.
*/
function get_symbol_definition_line(string $symbol, int $type): int
{
if (Loader::TYPE_CONSTANTS === $type) {
return 0;
}
if (Loader::TYPE_FUNCTION === $type) {
$reflection = new ReflectionFunction($symbol);
} else {
$reflection = new ReflectionClass($symbol);
}
return $reflection->getStartLine();
}

12
src/Psl/Internal/Loader.php
View File

@ -599,17 +599,17 @@ final class Loader
'Psl\Filesystem\Exception\RuntimeException', 'Psl\Filesystem\Exception\RuntimeException',
]; ];
private const TYPE_CONSTANTS = 1; public const TYPE_CONSTANTS = 1;
private const TYPE_FUNCTION = 2; public const TYPE_FUNCTION = 2;
private const TYPE_INTERFACE = 4; public const TYPE_INTERFACE = 4;
private const TYPE_TRAIT = 8; public const TYPE_TRAIT = 8;
private const TYPE_CLASS = 16; public const TYPE_CLASS = 16;
private const TYPE_CLASSISH = self::TYPE_INTERFACE | self::TYPE_TRAIT | self::TYPE_CLASS; public const TYPE_CLASSISH = self::TYPE_INTERFACE | self::TYPE_TRAIT | self::TYPE_CLASS;
private function __construct() private function __construct()
{ {