Making WordPress.org

Opened 2 years ago

Closed 3 months ago

Last modified 3 months ago

#2600 closed defect (reported-upstream)

source listing for _get_term_hierarchy() in code reference is not actually for that function

Reported by: pbiron Owned by:
Milestone: Priority: normal
Component: Developer Hub Keywords:


The code reference for _get_term_hierarchy(), the source listing begins at the wrong line number, L3896, instead of the correct L3166.

Change History (8)

#1 @SergeyBiryukov
2 years ago

  • Component changed from Codex to Developer Hub

#2 @coffee2code
18 months ago

#3242 was marked as a duplicate.

#3 @coffee2code
6 months ago

Ok, so I finally looked into this. I feared initially this was going to be a tricky problem with the parser. But it appears to be rather straightforward.

In [core32453], the @ignore dockblock tag was added to _get_term_hierarchy() as part of a general docs cleanup for that file. Prior to that commit, the function was marked @access private so it was regularly getting parsed into the Code Reference. As of that commit, the parser was directed to ignore parsing the function. The parser doesn't have state-change handling, so the docs for _get_term_hierarchy() have remained in an unchanged state since then. Naturally, code elsewhere in the file has since changed, so the stored source code line numbers no longer point to the appropriate lines.

I updated the line number for the function and re-cached the source code so the docs are correct for now. Going forward we need to revert the @ignore back to @access private, or we need to delete the function from the Code Reference.

@DrewAPicture: Was ignoring this sole function intentional? There are other private functions in the file that weren't ignored and I'm not sure why the change for this one.

This ticket was mentioned in Slack in #core-docs by coffee2code. View the logs.

6 months ago

#5 @DrewAPicture
6 months ago

I honestly have no idea why only that private function was ignored at that time.

There were definitely other private functions that were left alone. The change from @access private for that function may have been purely incidental at the time – when you're making general docs fixes in a big file, you tend to fix whatever you see. So it's possible that I just didn't touch the docs for the other private functions.

Based on the date difference between that changeset and [2431], it looks like the @ignore was added in that brief period when we were ignoring private functions, which would have fallen about 6 months before we started showing the private access messages in the Code Reference.

Lacking context I would even say we could just restore the @access private tag to it.

This ticket was mentioned in Slack in #meta-devhub by drew. View the logs.

6 months ago

#7 @coffee2code
3 months ago

  • Resolution set to reported-upstream
  • Status changed from new to closed

The fixing change for the core docs was submitted with a patch as #core45997.

In the meantime, I've been manually "fixing" the docs for this function to prevent the reported issue.

#8 @pbiron
3 months ago

@coffee2code thanx for your efforts to address this.

Note: See TracTickets for help on using tickets.