WordPress / WordPress/phpdoc-parser

DocBlock for hooks not parsed correctly in some cases

Open
#217 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
PHP
Stars
239
Forks
81
Avg merge
16h 29m
Merged PRs (30d)
8

Description

While parsing the source for a plugin, I came across a case where the DocBlock for a hook isn't parsed correctly.

The code contains the following:

/**
 * Filters the filename to be required.
 *
 * @since 1.2.3
 *
 * @param string $filename The filename to require.
 */
require apply_filters( 'my-filter', 'some filename' );

The hook gets imported (including the description), but for some reason the @since tag is not. Instead, @since tags from the file-level DocBlock are associated with the hook.

Changing the code to the equivalent:

/**
 * Filters the filename to be required.
 *
 * @since 1.2.3
 *
 * @param string $filename The filename to require.
 */
$filename = apply_filters( 'my-filter', 'some filename' );
require $filename;

works just fine.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the issue with the two PHP snippets in the issue and trace how hook DocBlocks are parsed. Done means the inline @since 1.2.3 tag is associated with the imported hook, while @since tags from the file-level DocBlock are not.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.