Parser

MMO\doc\js · 1 symbol · generated 30 Sep 2026

class

Parser

Extracts documentation from javascript sources, the way reflection extracts it from php.

class MMO\doc\js\Parser

Namespace: MMO\doc\js

There is no reflection for a `.js` file -- the code never runs here -- so this walks [`Lexer`](https://mmoframework.fr/documentation/mmo.doc/php/js/Lexer.md#lexer)'s tokens and recognises the handful of declaration shapes this codebase actually uses, then reads the jsdoc comment sitting above each one with the very same [`DocComment`](https://mmoframework.fr/documentation/mmo.doc/php/helpers/DocComment.md#doccomment) parser the php side uses (so `@param`, `@return`, `@throws`, `@example`, `@see`, `{@link }` all behave identically in both languages): | source | documented as | |---|---| | `goog.provide('MMO.core.Map')` | the file's declared namespaces | | `MMO.core.Map = class extends X {...}` | a class, with every member of its body | | `class Foo extends Bar {...}` | a class | | `MMO.elements.CustomElement = Base => class extends Base {...}` | a mixin, with every member of its body | | `MMO.core.strings.bytesize = function (a, b = 2) {...}` | a function | | `MMO.core.dom.$ = MMO.core.dom.query` | an alias constant | | `MMO.core.strings = {A: 1, b() {}}` | a namespace, with its keys as members | | `MMO.core.MAP_CHANGED = Symbol('...')` | a constant | Inside a class body it recognises methods, `static`/`async`/generator methods, `get`/`set` accessors, `#private` names and class fields -- and is careful about the one case a naive scanner always gets wrong: `get` and `set` are also perfectly ordinary *method names* (`MMO.core.Map` has both), told apart by whether a `(` follows immediately.

$symbols = (new \MMO\doc\js\Parser())->parseFile('/path/to/Map.js'); foreach ($symbols as $symbol) {echo $symbol['name'], ': ', $symbol['summary'], "\n";}

Index

	comments
	count
	filename
	language
	provides
	source
	symbols
	tokens
	accessorSignature($name, $getter, $setter, $modifiers)
	comment($doc)
	continuesExpression($i)
	endsOpen($i)
	examplesOf($comment)
	fieldSignature($name, $value, $modifiers)
	getProvides()
	isArrowHeader($i)
	isOpening($i)
	lineCommentsDoc($texts, $first, $i, $line, $doc)	Turn a kept run of `//` lines into a doc-comment-shaped token, or give the pending one back when there is nothing worth keeping.
	looksLikeConstant($name)
	matchBracket($i)
	mergeAccessors($members)	Fold each `get x()`/`set x()` pair into the single property it really is, the way a reader thinks of it -- with the getter's own doc comment and `@return {T}` type (a setter's jsdoc is discarde…
	methodSignature($name, $params, $modifiers)
	newMember($kind, $name, $comment, $line, $modifiers, $owner)
	newSymbol($kind, $name, $doc, $line)
	paramTag($comment, $name)
	parse($source, $filename)
	parseAssignment($start, $name, $i, $doc)	Parse `<name> = <value>` once the left-hand side is known, and turn the right-hand side into the matching kind of symbol.
	parseClass($i, $name, $doc)
	parseFile($filename)
	parseFunction($i, $name, $doc, $async)
	parseMembers($i, $end, $owner)	Parse a class body or an object literal into members.
	parseParam($from, $to, $comment)
	parseParams($i, $end, $comment)	Split a parameter list into `DocParam`, merging in whatever the jsdoc `@param` tags say about each one.
	parseStatement($i, $doc)	Parse one top-level statement, registering whatever symbol it declares.
	readLineComments($i, $doc)	Collect a run of consecutive `//` lines as a doc comment, so constants documented that way are not lost.
	readPath($i)	Read a dotted path (`MMO.core.Map`) starting at $i.
	reference($name)
	register($symbol)	Register a symbol, merging it into a same-named one already found (a class re-opened, a namespace extended).
	returnOf($comment)
	skipArrowHeader($i)
	skipSemicolon($i)
	skipStatement($i)
	split($name)	A symbol declared under an already-known namespace object becomes one of its members instead of a page of its own -- that is what makes `MMO.core.strings.bytesize` show up on the `MMO.core.strings`…
	statementEnd($i, $limit)	Find where a statement (or an object-literal entry) ends: the first `;` or `,` at depth 0, the first token on a new line when nothing is left open (javascript's automatic semicolon insertion), or $…
	stringAt($i)
	StripBanner($text) static	Drop the section banners this codebase draws with comments, which would otherwise be read as the documentation of whatever follows them -- and, worse, turn into setext `<h1>`s once rendered as mark…
	tagsOf($comment)	Every doc tag that is not already rendered as a first-class part of the model, kept in source order so the page can show `@see`, `@deprecated`, `@todo`, `@since`, `@author`...
	tagType($tag)
	text($from, $to)
	throwsOf($comment)
	type($text)	Build a `DocType` from a jsdoc type expression (`{number\|string}`, `{Array<MMO.core.Map>}`).
	typeAt($i)
	value($i)

Properties8

comments

protected array $comments = []

Type: array

count

protected int $count = 0

Type: int

filename

protected string $filename = ''

Type: string

language

protected string $language = 'js'

Type: string

provides

protected array $provides = []

Type: array

source

protected string $source = ''

Type: string

symbols

protected array $symbols = []

Type: array

tokens

protected array $tokens = []

Type: array

Methods45

accessorSignature($name, $getter, $setter, $modifiers)

Parser.php:438

protected function accessorSignature(string $name, bool $getter, bool $setter, array $modifiers): string

$name	string
$getter	bool
$setter	bool
$modifiers	array
returns	string

comment($doc)

Parser.php:564

protected function comment(?array $doc): MMO\doc\helpers\DocComment

$doc	null \| array
returns	DocComment	the parsed doc comment (empty when there is none), banner rules stripped.

continuesExpression($i)

Parser.php:916

protected function continuesExpression(int $i): bool

$i	int
returns	bool	true when the token at $i can only be the continuation of the expression on the line above.

endsOpen($i)

Parser.php:922

protected function endsOpen(int $i): bool

$i	int
returns	bool	true when the token at $i leaves the expression obviously unfinished (a trailing operator).

examplesOf($comment)

Parser.php:652

protected function examplesOf(MMO\doc\helpers\DocComment $comment): array

$comment	DocComment
returns	array	the `@example` blocks of a doc comment, as `{code, language}` entries.

fieldSignature($name, $value, $modifiers)

Parser.php:809

protected function fieldSignature(string $name, ?string $value, array $modifiers): string

$name	string
$value	null \| string
$modifiers	array
returns	string

getProvides()

Parser.php:97

function getProvides(): array

returns

array

the namespaces declared by the last parsed file.

isArrowHeader($i)

Parser.php:874

protected function isArrowHeader(int $i): bool

$i	int
returns	bool

isOpening($i)

Parser.php:836

protected function isOpening(int $i): bool

$i	int
returns	bool

lineCommentsDoc($texts, $first, $i, $line, $doc)

Parser.php:542

Turn a kept run of // lines into a doc-comment-shaped token, or give the pending one back when there is nothing worth keeping.

protected function lineCommentsDoc(array $texts, int $first, int $i, int $line, ?array $doc): array

$texts	array
$first	int	the index of the run's first token
$i	int	the index just past the run
$line	int	the line the run starts on
$doc	null \| array
returns	array	?array, 1: int}

looksLikeConstant($name)

Parser.php:794

protected function looksLikeConstant(string $name): bool

$name	string
returns	bool	true when $name reads like a constant (`SCREAMING_CASE`) rather than a variable.

matchBracket($i)

Parser.php:844

protected function matchBracket(int $i): int

$i	int	the index of an opening bracket
returns	int	the index of its matching closing bracket (the last token, when it is unbalanced)

mergeAccessors($members)

Parser.php:392

Fold each get x()/set x() pair into the single property it really is, the way a reader thinks of it -- with the getter's own doc comment and @return {T} type (a setter's jsdoc is discarded, matching what JHSCompiler's own documentation() extractor does), and marked readonly when no setter exists. Without this, every accessor pair would show up twice, under the same anchor.

protected function mergeAccessors(array $members): array

$members	array
returns	array

methodSignature($name, $params, $modifiers)

Parser.php:799

protected function methodSignature(string $name, array $params, array $modifiers): string

$name	string
$params	array
$modifiers	array
returns	string

newMember($kind, $name, $comment, $line, $modifiers, $owner)

Parser.php:711

protected function newMember( string $kind, string $name, MMO\doc\helpers\DocComment $comment, int $line, array $modifiers, string $owner ): MMO\doc\models\DocMember

$kind	string
$name	string
$comment	DocComment
$line	int
$modifiers	array
$owner	string
returns	DocMember

newSymbol($kind, $name, $doc, $line)

Parser.php:670

protected function newSymbol(string $kind, string $name, ?array $doc, int $line): MMO\doc\models\DocSymbol

$kind	string
$name	string	the fully qualified name
$doc	null \| array
$line	int
returns	DocSymbol	a symbol with its doc text, location and tags already filled in

paramTag($comment, $name)

Parser.php:599

protected function paramTag(MMO\doc\helpers\DocComment $comment, string $name): ?MMO\doc\helpers\DocTag

$comment	DocComment
$name	string
returns	null \| DocTag	the `@param` tag documenting $name, matched with or without brackets.

parse($source, $filename)

Parser.php:65

function parse(string $source, string $filename = ''): array

$source	string	the javascript source
$filename = ''	string	the name it is reported under (source links)
returns	array

parseAssignment($start, $name, $i, $doc)

Parser.php:156

Parse <name> = <value> once the left-hand side is known, and turn the right-hand side into the matching kind of symbol.

protected function parseAssignment(int $start, string $name, int $i, ?array $doc): int

$start	int	the index of the left-hand side (used only for the statement's line)
$name	string	the assigned, fully qualified name
$i	int	the index of the first token of the value
$doc	null \| array
returns	int	the index just past the statement

parseClass($i, $name, $doc)

Parser.php:213

protected function parseClass(int $i, string $name, ?array $doc): array

$i	int	the index of the `class` keyword
$name	string	the name the class is known under
$doc	null \| array
returns	array	DocSymbol, 1: int} the symbol, and the index just past the class body

parseFile($filename)

Parser.php:56

function parseFile(string $filename): array

$filename	string
returns	array	the symbols the file declares, in source order

parseFunction($i, $name, $doc, $async)

Parser.php:254

protected function parseFunction(int $i, string $name, ?array $doc, bool $async = false): array

$i	int	the index of the `function` keyword, or of an arrow function's first token
$name	string
$doc	null \| array
$async = false	bool
returns	array	DocSymbol, 1: int}

parseMembers($i, $end, $owner)

Parser.php:299

Parse a class body or an object literal into members.

protected function parseMembers(int $i, int $end, string $owner): array

$i	int	the index just past the opening `{`
$end	int	the index of the matching `}`
$owner	string	the name members are documented as belonging to
returns	array

parseParam($from, $to, $comment)

Parser.php:469

protected function parseParam(int $from, int $to, MMO\doc\helpers\DocComment $comment): MMO\doc\models\DocParam

$from	int
$to	int
$comment	DocComment
returns	DocParam	one parameter, from the tokens in `[$from, $to]`.

parseParams($i, $end, $comment)

Parser.php:453

Split a parameter list into DocParam, merging in whatever the jsdoc @param tags say about each one.

protected function parseParams(int $i, int $end, MMO\doc\helpers\DocComment $comment): array

$i	int	the index just past the opening `(`
$end	int	the index of the matching `)`
$comment	DocComment
returns	array

parseStatement($i, $doc)

Parser.php:110

Parse one top-level statement, registering whatever symbol it declares.

protected function parseStatement(int $i, ?array $doc): int

$i	int	the index of its first token
$doc	null \| array	the doc comment sitting above it, if any
returns	int	the index just past the statement

readLineComments($i, $doc)

Parser.php:510

Collect a run of consecutive // lines as a doc comment, so constants documented that way are not lost.

protected function readLineComments(int $i, ?array $doc): array

A run is only kept when nothing but comment lines separate it from what it documents.

$i	int
$doc	null \| array	the pending doc comment, kept when the `//` run turns out to be a separator banner
returns	array	?array, 1: int}

readPath($i)

Parser.php:933

Read a dotted path (MMO.core.Map) starting at $i.

protected function readPath(int $i): array

$i	int
returns	array	?string, 1: int} the path (null when there is none) and the index just past it

reference($name)

Parser.php:788

protected function reference(string $name): array

$name	string
returns	array	string, short: string, url: null} a reference to another symbol, left unlinked.

register($symbol)

Parser.php:741

protected function register(MMO\doc\models\DocSymbol $symbol): void

$symbol	DocSymbol
returns	void

returnOf($comment)

Parser.php:611

protected function returnOf(MMO\doc\helpers\DocComment $comment): ?array

$comment	DocComment
returns	null \| array	the `{type, description}` the `@return`/`@returns` tag declares.

skipArrowHeader($i)

Parser.php:866

protected function skipArrowHeader(int $i): ?int

$i	int	the index of an `=`/`(`/name that may start an arrow function's parameter list
returns	null \| int	the index just past the `=>`, or null when this is not an arrow function

skipSemicolon($i)

Parser.php:947

protected function skipSemicolon(int $i): int

$i	int
returns	int	the index just past an optional `;` -- what follows a block that already ended a statement.

skipStatement($i)

Parser.php:952

protected function skipStatement(int $i): int

$i	int
returns	int	the index just past the statement starting at $i, whatever it is.

split($name)

Parser.php:764

A symbol declared under an already-known namespace object becomes one of its members instead of a page of its own -- that is what makes MMO.core.strings.bytesize show up on the MMO.core.strings page.

protected function split(string $name): array

$name	string
returns	array	string, 1: string} the namespace and the short name

statementEnd($i, $limit)

Parser.php:885

Find where a statement (or an object-literal entry) ends: the first ; or , at depth 0, the first token on a new line when nothing is left open (javascript's automatic semicolon insertion), or $limit.

protected function statementEnd(int $i, ?int $limit = null): int

$i	int
$limit = null	null \| int	an upper bound (the enclosing `}` when scanning a class body)
returns	int	the index just past the statement

stringAt($i)

Parser.php:825

protected function stringAt(int $i): ?string

$i	int
returns	null \| string	the string literal at $i, unquoted.

StripBanner($text)

staticParser.php:579

Drop the section banners this codebase draws with comments, which would otherwise be read as the documentation of whatever follows them -- and, worse, turn into setext <h1>s once rendered as markdown (a line of = right under a line of text *is* a heading).

protected static function StripBanner(string $text): string

A rule line is dropped wherever it appears; a comment that is nothing but a title over a rule (`Change events` + `================`) is a banner in full and yields no documentation at all.

$text	string	the raw comment, delimiters included
returns	string	the comment body, without its delimiters or leading asterisks

\MMO\doc\js\Parser::StripBanner("*\n * Change events\n * ======== *" . "/"); // ''

tagsOf($comment)

Parser.php:633

Every doc tag that is not already rendered as a first-class part of the model, kept in source order so the page can show @see, @deprecated, @todo, @since, @author... without this parser having to know what each of them means.

protected function tagsOf(MMO\doc\helpers\DocComment $comment): array

$comment	DocComment
returns	array	string, text: string}>

tagType($tag)

Parser.php:556

protected function tagType(?MMO\doc\helpers\DocTag $tag): string

$tag	null \| DocTag
returns	string	the `{type}` a tag declares -- read from the tag's parsed `type` when `DocTag` knew how to split it off, and from the raw text otherwise (`@type {T}`, `@css {color}`, ...)

text($from, $to)

Parser.php:831

protected function text(int $from, int $to): string

$from	int
$to	int
returns	string	the source text covering the tokens `[$from, $to]`.

throwsOf($comment)

Parser.php:618

protected function throwsOf(MMO\doc\helpers\DocComment $comment): array

$comment	DocComment
returns	array	the `{type, description}` of every `@throws` tag.

type($text)

Parser.php:776

Build a DocType from a jsdoc type expression ({number|string}, {Array<MMO.core.Map>}). Nothing is resolved here -- linking is the documentor's job, since only it knows which symbols exist across the whole package (JSDocumentor::link).

protected function type(string $text): ?array

$text	string
returns	null \| array

typeAt($i)

Parser.php:820

protected function typeAt(int $i): ?string

$i	int
returns	null \| string

value($i)

Parser.php:816

protected function value(int $i): ?string

$i	int
returns	null \| string