What:
When the MediaWiki source code documentation is produced locally, a significant number of warnings are generated by Doxygen that reference a total of 56 individual Core files. This task is to look at all of the files involved and determine whether the warnings are false positives or actual problems in the Doxygen code markup.
Outcome:
The documentation when generated with php maintenance/mwdocgen.php should not generate any warnings.
| Status | Subtype | Assigned | Task | ||
|---|---|---|---|---|---|
| Resolved | • holger.knust | T248706 Resolve Doxygen warnings thrown when the Mediawiki Core documentation is being generated | |||
| Resolved | hashar | T242155 Update Doxygen in CI to 1.8.17 or greater | |||
| Duplicate | hashar | T250424 Update operations/debs/doxygen to 1.8.17 or later and release into apt.wikimedia.org |
Remaining warnings after 587361 was applied
/data/git/wmf/gerrit/mediawiki/core/includes/api/ApiBlockInfoTrait.php:77: warning: unbalanced grouping commands
/data/git/wmf/gerrit/mediawiki/core/includes/changetags/ChangeTagsList.php:24: warning: documented symbol 'ChangeTagsLogItem $current' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/includes/installer/MysqlUpdater.php:31: warning: documented symbol 'Wikimedia Rdbms DatabaseMysqlBase $db' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/includes/parser/PPDPart.php:24: warning: documented symbol 'int $eqpos' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/includes/parser/PPDPart.php:25: warning: documented symbol 'int $commentEnd' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/includes/parser/PPDPart.php:26: warning: documented symbol 'int $visualEnd' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/includes/parser/PPDPart_Hash.php:23: warning: documented symbol 'string[] $out' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/includes/parser/PPDStackElement.php:24: warning: documented symbol 'int $startPos' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/includes/parser/PPDStackElement_Hash.php:23: warning: documented symbol 'PPDPart_Hash[] $parts' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/includes/parser/PPFrame.php:24: warning: documented symbol 'int $depth' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/includes/parser/PPFrame.php:25: warning: documented symbol 'PPFrame $parent' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/includes/profiler/output/ProfilerOutputDump.php:25: warning: documented symbol 'ProfilerXhprof $collector' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/includes/Revision/MutableRevisionRecord.php:40: warning: documented symbol 'MutableRevisionSlots MediaWiki::Revision::$mSlots' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/includes/revisiondelete/RevDelArchivedFileItem.php:28: warning: documented symbol 'RevDelArchivedFileList $list' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/includes/revisiondelete/RevDelList.php:30: warning: documented symbol 'RevDelItem $current' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/includes/revisiondelete/RevDelRevisionItem.php:26: warning: documented symbol 'RevDelRevisionList $list' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/maintenance/dev/includes/router.php:74: warning: documented symbol 'foreach( $lines as $line) if(preg_match('#^text/#', $mime) else)' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/maintenance/mcc.php:222: warning: documented symbol 'switch' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/maintenance/storage/testCompression.php:110: warning: documented symbol 'foreach' was not declared or defined.
/data/git/wmf/gerrit/mediawiki/core/maintenance/updateCredits.php:77: warning: documented symbol 'foreach' was not declared or defined.I had hoped that ApiBlockInfoTrait.php:77: warning: unbalanced grouping commands would go away with release 1.8.17 as per Doxygen Regression fix, but 1.8.18 still throws the same warning when tested locally. Not sure if the grouping can be removed altogether, as it does not seem to be rendered in the current docs
Change 587361 had a related patch set uploaded (by Holger Knust; owner: Holger Knust):
[mediawiki/core@master] doxygen: Changed Doxygen tags that would cause warnings when run locally
Change 587361 merged by jenkins-bot:
[mediawiki/core@master] doxygen: Changed Doxygen tags causing warnings during documentation generation
The remaining warnings fall into 2 groups:
The " unbalanced grouping commands" warning seemed to be caused by a Doxygen regression but is still occurring in the latest version 1.8.18 in which the regression was resolved. I am planning on taking another look at the second group at a later point in time so I moved it back to the backlog for now.
Change 591048 had a related patch set uploaded (by Holger Knust; owner: Holger Knust):
[mediawiki/core@master] docs: Restore welcome message on docs landing page
Change 591048 merged by jenkins-bot:
[mediawiki/core@master] docs: Restore welcome message on docs landing page
This task apparently depended on an upgrade of Doxygen. CI now runs Doxygen 1.8.19 so that would unblock this task if the Doxygen version was a blocker.
It depended on it, in order to get support for @noop which we can then use as alias target for some of the annotations we use intenrally that Doxygen should ignore (and would otherwise cause warnings or bogus output).
Yes and I got a newer Doxygen which does support \noop. I have proposed a patch for both @phan (T241182) and @suppress. That should move us one step forward.
I guess we will want some Doxygen job that runs for each patchset, possibly tuned to not generate the Graphviz graphs.
Looks like these have all been resolved. There is still a little bit of noise in the output at https://integration.wikimedia.org/ci/job/mediawiki-core-doxygen-docker/, but I don't think that's worth fixing. I looked at these handful of errors and they are all about CLI syntax in maintenance scripts or Phan annotations that it doesn't understand and doesn't need to understand. That's just what we get for piping PHP code through a regex filter to try and produce Java-like syntax to feed for Doxygen, it's not going to parse it perfectly without warnings, but we're now free of any issues that affect the doc output we care about, I think!