PHPDoc comments

[muglug]

Supposing we wanted the tool to understand PHP docblocks, would that grammar have to live in https://github.com/tree-sitter/tree-sitter-phpdoc or similar?

And how could that be plugged into tree-sitter-php?

[patrickt]

Yes, the recommended way to parse things like documentation comments is to write a separate parser, as we do with https://github.com/tree-sitter/tree-sitter-jsdoc for JS and TS. You would then use both these parsers in parallel, with one pass to parse comments and one to parse the rest of the program text.

[maxbrunsfeld]

For syntax highlighting, we have an established system for "composing" parsers like this. You have to write an "injection query" that tells our syntax highlighter which ranges should be re-parsed with a different language.

Example: https://github.com/tree-sitter/tree-sitter-javascript/blob/master/queries/injections.scm
Docs: https://tree-sitter.github.io/tree-sitter/syntax-highlighting#language-injection

[cfroystad]

First, thanks for making Psalm, @muglug - it makes it possible to sleep at night while working with PHP 🙂

Regarding phpdoc, I came across a preexisting implementation. I've not tested it myself, but from a quick look at the code it seems to need a bit more work to be fully usable in the context of Psalm/phpStan.

The same applies to tree-sitter-php, unfortunately. In it's current form I'd be surprised if it could be used by Psalm (I'm assuming that's the intent) due to missing a few fundamental language constructs like string parsing, references, and probably a few more I've yet to identify. They're being added slowly, but we're not there yet.

[claytonrcarter]

FWIW I picked up the work from https://github.com/john-nguyen09/tree-sitter-phpdoc and have been tinkering with it for inclusion in my Atom PR (atom/language-php#438). Still some more to do for complete support, but it seems like it's currently good enough for syntax highlighting. It's at https://github.com/claytonrcarter/tree-sitter-phpdoc

[weeman1337]

What about moving the tree-sitter phpdoc repo to the tree-sitter project? From what I have read above there is still room to improve. But in my opinion having it now is better than no tree-sitter support for php doc blocks at all.

[mikehaertl]

@claytonrcarter Thanks for your work so far. Could you comment on your plans with your repository? I'd like to add it as experimental parser source to https://github.com/nvim-treesitter/nvim-treesitter. But for full support they probably expect some ongoing maintainership.

[claytonrcarter]

@weeman1337 I'd be fine w/ that, if tree-sitter org folks would like that.

@mikehaertl Though I have no intentions to stop maintaining it, I am also unwilling to make any sort of promises regarding ongoing maintenance.