Page MenuHomePhabricator

Fix Doxygen "Warning: Found unknown command"
Closed, ResolvedPublic

Description

I took the output from the latest https://integration.wikimedia.org/ci/job/mediawiki-core-doxygen-publish/ build and filtered it down to this unique list:

warning: Found unknown command `\abstract'
warning: Found unknown command `\access'
warning: Found unknown command `\codingStandardsIgnoreEnd'
warning: Found unknown command `\comment'
warning: Found unknown command `\const'
warning: Found unknown command `\Constants'
warning: Found unknown command `\cover'
warning: Found unknown command `\covers'
warning: Found unknown command `\dataProvider'
warning: Found unknown command `\default'
warning: Found unknown command `\depends'
warning: Found unknown command `\embed'
warning: Found unknown command `\expectedException'
warning: Found unknown command `\fixme'
warning: Found unknown command `\Formatter'
warning: Found unknown command `\FormatterInterface'
warning: Found unknown command `\gmail'
warning: Found unknown command `\Handler'
warning: Found unknown command `\HandlerInterface'
warning: Found unknown command `\import'
warning: Found unknown command `\LegacyFormatter'
warning: Found unknown command `\LegacyHandler'
warning: Found unknown command `\LegacyLogger'
warning: Found unknown command `\LegacySpi'
warning: Found unknown command `\licence'
warning: Found unknown command `\Log'
warning: Found unknown command `\LogEvent'
warning: Found unknown command `\Logger'
warning: Found unknown command `\LoggerFactory'
warning: Found unknown command `\LoggerInterface'
warning: Found unknown command `\LogLevel'
warning: Found unknown command `\LogstashFormatter'
warning: Found unknown command `\MediaWiki'
warning: Found unknown command `\medium'
warning: Found unknown command `\Monolog'
warning: Found unknown command `\MonologSpi'
warning: Found unknown command `\noflip'
warning: Found unknown command `\NullLogger'
warning: Found unknown command `\NullSpi'
warning: Found unknown command `\Psr'
warning: Found unknown command `\r'
warning: Found unknown command `\s'
warning: Found unknown command `\Spi'
warning: Found unknown command `\SyslogHandler'
warning: Found unknown command `\TODO'
warning: Found unknown command `\uses'
warning: Found unknown command `\Utils'
warning: Found unknown command `\Validator'
warning: Found unknown command `\WikiProcessor'
warning: Found unknown command `\x80'
warning: Found unknown command `\x8E'
warning: Found unknown command `\x8F'
warning: Found unknown command `\xB8'
warning: Found unknown command `\xC3'
warning: Found unknown command `\xE2'

That means the ALIASES configuration at maintenance/Doxygen:50 is not working as expected.

Event Timeline

Krinkle raised the priority of this task from to Needs Triage.
Krinkle updated the task description. (Show Details)
Krinkle added a subscriber: Krinkle.
Restricted Application added a subscriber: Aklapper. · View Herald Transcript
Addshore added a subscriber: Addshore.

Also tagging with Wikidata as we also have this problem, although it is bigger for us, as we have more namespaces...

Very small sample output:

/src/repo/includes/Parsers/WikibaseStringValueNormalizer.php:8: warning: Found unknown command '\Normalizers'
/src/repo/includes/Parsers/WikibaseStringValueNormalizer.php:8: warning: Found unknown command '\StringNormalizer'
/src/repo/includes/Parsers/WikibaseStringValueNormalizer.php:8: warning: Found unknown command '\Wikibase'
/src/repo/includes/Parsers/WikibaseStringValueNormalizer.php:8: warning: Found unknown command '\StringNormalize'

Change 562292 had a related patch set uploaded (by Addshore; owner: Addshore):
[mediawiki/extensions/Wikibase@master] doxygen, ignore command error caused by php namespaces

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

Krinkle claimed this task.

This task is for mediaiwiki/core where I believe all of these have been fixed now. If there are any particularly challenging ones left, I suggest creating a separate task for that.

One known issue is that Doxygen doesn't have a way to skip a tag that serves no doc-related purpose (e.g. /** @phan-suppress PhanFooBar */). This is tracked at T233788.

Change 562292 merged by jenkins-bot:
[mediawiki/extensions/Wikibase@master] doxygen, ignore pointless errors & fix others

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