Opened 7 years ago

Closed 6 years ago

Last modified 6 years ago

#2600 closed defect (bug) (reported-upstream)

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

Reported by: pbiron's profile 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
7 years ago

  • Component changed from Codex to Developer Hub

#2 @coffee2code
7 years ago

#3242 was marked as a duplicate.

#3 @coffee2code
6 years 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 years ago

#5 @DrewAPicture
6 years 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 years ago

#7 @coffee2code
6 years 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
6 years ago

@coffee2code thanx for your efforts to address this.

Note: See TracTickets for help on using tickets.