#2600 closed defect (bug) (reported-upstream)
source listing for _get_term_hierarchy() in code reference is not actually for that function
Reported by: |
|
Owned by: | |
---|---|---|---|
Milestone: | Priority: | normal | |
Component: | Developer Hub | Keywords: | |
Cc: |
Description
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)
#3
@
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
@
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
@
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.
#3242 was marked as a duplicate.