Page MenuHomePhabricator

Resolve Doxygen warnings thrown when the Mediawiki Core documentation is being generated
Open, LowPublic

Description

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.

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptMar 27 2020, 7:27 PM
holger.knust triaged this task as Low priority.Mar 30 2020, 2:37 PM
holger.knust added a comment.EditedApr 7 2020, 10:30 PM

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

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

daniel raised the priority of this task from Low to Medium.Apr 15 2020, 4:49 PM

Change 587361 merged by jenkins-bot:
[mediawiki/core@master] doxygen: Changed Doxygen tags causing warnings during documentation generation

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

holger.knust lowered the priority of this task from Medium to Low.Apr 16 2020, 8:53 PM

The remaining warnings fall into 2 groups:

  1. Inherited properties that cause Doxygen warnings
  2. Maintenance scripts issues

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

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

Change 591048 merged by jenkins-bot:
[mediawiki/core@master] docs: Restore welcome message on docs landing page

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

hashar added a subscriber: hashar.May 25 2020, 2:22 PM

CI now has Doxygen 1.8.17.