Page MenuHomePhabricator

Doxygen: Ignore `@phan` notation (and more)
Closed, ResolvedPublic

Description

Doxygen sometimes reads and tries to interpret phan notation; it should ignore it. Specific tags that I have seen

@phan-file-suppress

@phan-var

@phan-param

@phan-return

@return-taint

Event Timeline

Restricted Application added subscribers: Liuxinyu970226, Aklapper. · View Herald Transcript

Change 559618 had a related patch set uploaded (by DannyS712; owner: DannyS712):
[mediawiki/core@master] Doxygen: Fix ignoring @phan notation

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

Change 559618 merged by jenkins-bot:
[mediawiki/core@master] Doxygen: Fix ignoring @phan notation, also ignore @return-taint

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

Change 563330 had a related patch set uploaded (by DannyS712; owner: DannyS712):
[mediawiki/core@master] Revert "Doxygen: Fix ignoring @phan notation, also ignore @return-taint"

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

DannyS712 moved this task from Awaiting review and deployment to Reports on the User-DannyS712 board.

Didn't actually fix the issues. I've created a revert, and will leave this for someone else

Change 563330 merged by jenkins-bot:
[mediawiki/core@master] Revert "Doxygen: Fix ignoring @phan notation, also ignore @return-taint"

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

Change 571559 had a related patch set uploaded (by Anomie; owner: Anomie):
[mediawiki/core@master] Improve Doxygen aliases

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

Upstream change: https://github.com/doxygen/doxygen/issues/1413 which has a patch in Doxygen master branch https://github.com/doxygen/doxygen/pull/7264 . That introduces a \noop command to strip all content.

Doxygen 1.8.17 has been released which includes the new @noop tag. Next step: Upgrade Doxygen in WMF CI.

These @phan- tags can also be aliased to @noop which should solve this.

This task apparently depended on an upgrade of Doxygen. CI now runs Doxygen 1.8.19.

So we should now be able to alias Phan markers to \noop. A previous attempt was done in 74ae1f143c5c61d7250cc0ceafe713ddbb270ace

Change 670854 had a related patch set uploaded (by Hashar; owner: Hashar):
[mediawiki/core@master] doc: strip content of @suppress or @phan annotations

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

Change 670854 abandoned by Hashar:
[mediawiki/core@master] doc: Let Doxygen strip content of @suppress or @phan annotations

Reason:
Bah Anomie did the exact same thing a year ago and I missed his change while browsing the change. So abandoning in favor of https://gerrit.wikimedia.org/r/c/mediawiki/core/ /571559 which has a better commit message and some other enhancements. Sorry Timo!

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

Change 571559 merged by jenkins-bot:
[mediawiki/core@master] docs: Improve Doxygen aliases and map more tool annotations to @noop

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

hashar claimed this task.

The @phan annotation is now aliases to \noop which ignores the content entirely.

It seems Doxygen stops the annotation parsing on dashes (-) hence a code such as:

@phan-var whatever

Would be interpreted as:

Annotation@phan
Payload-var whatever

And since we have @phan aliases to \noop, that should strip it.

For the few examples I have checked, it seems to be working now.