OOUI's generated docs link wrong source files for inherited methods
Open, Stalled, Needs TriagePublicBUG REPORT
Actions

Assigned To

None

Authored By

	Jack_who_built_the_house
	Jun 23 2024, 4:05 PM

Description

Steps to replicate the issue (include links if applicable):

Go to https://doc.wikimedia.org/oojs-ui/master/js/OO.ui.html#.alert
I want to see the options list. The docs say "Additional options, see OO.ui.MessageDialog#getSetupProcess"
This is not a link, but OK, I search this, find and click OO.ui.MessageDialog#getSetupProcess

What happens?:

Options are still not explaned
The source links to Window.js, line 355

What should have happened instead?:

The actual source is https://doc.wikimedia.org/oojs-ui/master/js/dialogs_MessageDialog.js.html#line148
Options are explained there

Context: T185396

Details

Related Changes in Gerrit:

	Subject	Repo	Branch	Lines +/-
	JSDoc: don't @inheritdoc when params are different	oojs/ui	master	+26 -2
	JSDoc: add {@link} to some links	oojs/ui	master	+6 -6

Customize query in gerrit

Related Objects

Mentioned Here: T368287: JSDuck to JSDoc: decide how to handle mixed `@inheritdoc`s
T185396: Replace jsduck with JSDoc3 in OOUI

Event Timeline

Jack_who_built_the_house created this task.Jun 23 2024, 4:05 PM

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJun 23 2024, 4:05 PM

Jack_who_built_the_house updated the task description. (Show Details)Jun 23 2024, 4:07 PM

Jack_who_built_the_house added a project: OOUI.Jun 23 2024, 4:11 PM

Jack_who_built_the_house added a project: Documentation.

Change #1048881 had a related patch set uploaded (by Novem Linguae; author: Novem Linguae):

[oojs/ui@master] JSDoc: add {@link} to some links

https://gerrit.wikimedia.org/r/1048881

gerritbot added a project: Patch-For-Review.Jun 23 2024, 4:29 PM

Change #1048884 had a related patch set uploaded (by Novem Linguae; author: Novem Linguae):

[oojs/ui@master] JSDoc: don't @inheritdoc when params are different

https://gerrit.wikimedia.org/r/1048884

Novem_Linguae claimed this task.Jun 23 2024, 4:38 PM

Novem_Linguae removed a project: JSDoc WMF theme.

Good job, thanks! So it's misplaced @inheritdoc that is to blame.

But wait... If @inheritdoc erases all documentation, it erases "Source" as well. So, while the problem with parameters is alleviated, it's still wrong source files that are linked. JSDuck had this right.

Could the behavior of @inheritdoc be changed? I'll tag "JSDoc WMF theme" back, because of course a fundamental solution would be preferred.

Change #1048881 merged by jenkins-bot:

[oojs/ui@master] JSDoc: add {@link} to some links

https://gerrit.wikimedia.org/r/1048881

Jack_who_built_the_house added a parent task: T368287: JSDuck to JSDoc: decide how to handle mixed `@inheritdoc`s.Jun 25 2024, 1:26 AM