The current order is decided based on whatever order Doxygen
encountered the `@defgroup myname Title Here` commands when
recursively traversing the source code directories (INPUT).
By default, it is not based on the identifier (group name) or display
label (group title), which means we end up with the following
on doc.wikimedia.org:
* API
* Recent changes (!)
* Change tagging
* Debug
* ExternalStorage
* Profiling
* ExtensionRegistry (!)
* ResourceLoader
* Upload
* Maintenance (!)
Because internally these are traversed as:
* includes/api
* includes/changes
* includes/registration
* maintenance/
But that's by no means known, relevant, or intuitive to a reader
of the docs; even for contributors that know where the files are,
they probably don't realize that maintenance/ comes after all
includes.
Bug: T364652
Change-Id: I3f03ae5bcc902aa2df020b7d5aa404c42829320c
Based on CI output, and what `doxygen -s -u` does automatically.
Diff minimised to only differences that fix warnings. Verbose
comments and copies of new default values are left uncommitted.
* HTML_TIMESTAMP=YES -> TIMESTAMP=YES
Renamed in 1.9.7.
https://github.com/doxygen/doxygen/commit/27933ab863
* FORMULA_TRANSPARENT=YES
DOT_TRANSPARENT=YES
No longer configurable since 1.9.5.
https://github.com/doxygen/doxygen/commit/8b7822cb67
* DOT_FONTNAME=Helvetica -> DOT_COMMON_ATTR
DOT_FONTSIZE=10 -> DOT_COMMON_ATTR
Renamed in 1.9.5.
https://github.com/doxygen/doxygen/commit/4bfd8297
Matches default.
https://doxygen.nl/manual/config.html#cfg_dot_common_attr
> The default value is: labelfontname=Helvetica,labelfontsize=10.
* DIA_PATH
MSCFILE_DIRS
Moved to a different section by `doxygen -s -u`.
Change-Id: I6354dc34af3aba6c0132f31fd290154ae54942c4
* Prefer the MW_INSTALL_PATH constant where possible.
* For input and output, there is no need to specify full paths,
only to strip the prefix again afterwards.
See also Doxyfile in any repo that is not mediawiki/core where we
already set the path relative to the project directory, e.g.
"src/" as input and "docs" as output.
<https://codesearch.wmcloud.org/search/?q=INPUT%7COUTPUT&files=Doxyfile>
Test Plan:
* `php maintenance/mwdocgen.php --file docs,includes/libs/objectcache/`
Change-Id: I4119161accdc665d0e4d0d4e49d0c42c68f8e2a2
I've upgraded Doxygen to 1.9.8 in WMF CI (Ie025bd8a5e9), and among
the bug fixes was https://github.com/doxygen/doxygen/issues/9047,
which makes it possible to use tags that contain dashes in ALIASES.
Change-Id: Ida5fddb89b76445922a87904745eff0a1e299043
Dumping many kinds of object with var_dump() leads to dumping the whole
address space, because a chain of references leads to MediaWikiServices.
So, introduce a trait which replaces the problematic properties with a
placeholder, if their doc comment contains @noVarDump.
Bug: T277618
Change-Id: Ifa685c26fbc5317d0359544289ec3f433ec4fedf
* COLS_IN_ALPHA_INDEX: No longer supported.
* CLASS_DIAGRAMS=NO, migrated to CLASS_GRAPH=TEXT
Deprecated for several years. New config form is already supported
by the version used in WMF CI (Doxygen 1.9.1)
Change-Id: Ic72d568f79e824e3e12ce273e76b6d7817647d44
For reasons not yet understood, during CI jobs for Git release tags,
the doc publishing pipeline is scanning extensions directories even
on core-only builds.
This was realized when investigating an issue with a large fixture
file in extensions/CirrusSearch/tests/ ("interwiki.php") causing
Doxygen to crash.
When reproducing the issue locally, I found that numerous node_modules,
vendor were also being scanned that didn't need to be.
Also exclude the 'cache' dir from core $IP while at it.
Bug: T317451
Change-Id: I696f1e7edeaf7bf12fbf17613cc9ee5c8dd846b0
This will remove some noise from long classes where currently these
members are listed before the public methods, which makes the docs
harder to navigate. The audience of doc.wikimedia.org where we
show this, I think is not likely to be interested in private members
and methods. That can always be found when navigating within a text
editor of course, where one is likely to interact with private methods.
For example, at https://doc.wikimedia.org/mediawiki-core/master/php/classWANObjectCache.html
the private members are before the main class docs render.
Change-Id: I8fda01f653e9cec311ecb10df98c3f871de267e6
This defaulted to plain text which looked out of place. Render it
in the same way as `@stable` annotations instead.
Change-Id: Ia7cc46fc89ce1f0a4ba6c5e47514cbed92f5c505
For some reason, @access is outputting a literal "\n" instead of the
newline that's supposed to generate. It seems to only ever be followed
by "public", "private", or "protected", so just remove the newline.
On the other hand, "@private" and so on are sometimes followed by text.
Instead of using @access, use a custom @par to produce nicer output.
"@internal" is being used now something like "@private", to indicate
things that are public for PHP access rules but should be treated as
private. Unfortunately Doxygen has its own "@internal", so we need to
override it.
We've also started using "@unstable", which Doxygen doesn't know about.
Doxygen 1.8.17 introduces "@noop", which allows us to alias annotations
such that they do not result in strange of partial output in docs.
Wikimedia CI is now on 1.8.19.
Fix "@suppress", "@codeCoverageIgnore", and
"@codingStandardsIgnore(Start|End)" by using this.
Bug: T233788
Bug: T241182
Change-Id: Idc7ef2afa6cdf8c15f0ca5e7e96e67c3a4374a8a
To improve generated docs for hook interfaces, this patch adds
an alias that renders the stable for implementation tag in the
Doxygen output.
Bug: T253815
Change-Id: I866afb318de35744976942d38a17cf429c68a34d
Doxygen defaults to generate the latex output, it always has been
disabled until babe0874ce which unexpectedly turned it on assuming it
came disabled by default.
Change-Id: Iae38b3816514a11f0c0ae81ab1d840862cc53bd3
Updated Doxygen markup in several .php files triggering warnings when mwdocgen.php is executed. Removed
obsolete settings MSCGEN_PATH and TCL_SUBST from Doxyfile. The former would generate a warning in 1.8.16
while TCL support was removed in 1.8.18. Since TCL_SUBST was blank anyway, it was removed prior to getting
to .18 in production. Increased DOT_GRAPH_MAX_NODES from 50 to 200 since Doxygen complained about it being
too low for API and Maintenance.
Bug: T248706
Change-Id: I9c67f0807d1b43089d351263d4f591dee5501f36
Adds an exclude pattern to prevent READMEs within the
maintenance directory from being included in the MediaWiki
Doxygen output.
Bug: T87796
Change-Id: I85231880ea58d1fbcbb132ed8630b6ce77b5c00d
The FileRepo, FileBackend, and JobQueue classes include documentation
files that don’t appear in the generated Doxygen docs. This PR:
* Converts these files to Markdown
* Links to each file from the respective class description
* Adds an ingroup tag so the files appear in the sidebar at the
module level
* Updates the exclude pattern in the Doxyfile to surface these pages
Bug: T87796
Change-Id: I94f0636ab489d741ab505f15da43a5d63c1ca61a
Disable warnings for methods that are missing documentation,
or have invalid documentation.
While useful in theory, in practice this is almost entirely noise
that can be ignored. Doxygen falls back very well when it encounters
"invalid" documentation (e.g. render the type hint as plain text),
which is usually the right solution.
For example "Foo[]" means an array of "Foo" objects, but may
yield a warning for "unknown Foo[]" type. The fallback is to
not make a 404 link for "Foo[]", but render it as plain text
which seems desirable.
We already enforce validity in a better way with PHPCS and Phan,
which makes Doxygen's (limited and often incorrect) validation
obsolete.
Change-Id: I90000a4e33205e15ffabc8aeba0117615f1fd163
This makes it more future-proof so that when more files are
added, they are excluded by default. If and when we do get a file
that is intended for this, it's likely such commit will test it
and find it doesn't work and then whitelist accordingly.
Change-Id: I3b8e421724d45e6aaecea58238f430a87cbbe977
These are to create pages with an overview of `@bug` and `@test`
annotations of which there are none in MediaWiki core in doc block
comments, like `/**`. As far as I know, there is also no practice
or plans to start using these or to use Doxygen as a way to
organise such work (we use Phabricator instead to report things
that are broken and/or should have tests).
Bug: T232104
Change-Id: I1056f22c38b11157ac7b5a23e9838978e8901171
Follows-up fec6692394, which excluded 'tests/' from indexing,
which means these aliases are no longer needed.
Change-Id: Ice6be877b8f526f26ef9657a335142d07428fa6e
Also remove redundant sections from the config file that all
relate to features that are unconditionally disabled for us
and by default. They were all no-ops because the corresponding
"GENERATE_"- config is NO by default as well.
Per <http://www.doxygen.nl/manual/config.html>.
Bug: T232104
Change-Id: Ibd81f23922f1994be6579fcd8e1ece5e9f995905
These are not relevant for Doxygen. Disable these so that they
are omitted from the description text, and also don't produce
warning noise in the CI builds.
Bug: T232104
Change-Id: Ieb89677097c60bbdd45c1c187d1c1048cc307e57
Lots of methods are missing documentation for methods in favour
of an unhelpful description text containing "@inheritDocs", leading
to warnings in CI during the doc building stage:
> mediawiki/includes/resourceloader/ResourceLoaderLessVarFileModule.php:9:
> warning: Found unknown command '\inheritDoc'
Before:
> ◆ ResourceLoaderLessVarFileModule::getMessages ( )
> Description
> @inheritDoc
>
> Reimplemented from ResourceLoaderFileModule.
> Definition at line 26 of file ResourceLoaderLessVarFileModule.php.
After:
> ◆ ResourceLoaderLessVarFileModule::getMessages ( )
> Description
> Gets list of message keys used by this module.
>
> Returns
> array List of message keys
>
> Reimplemented from ResourceLoaderFileModule.
> Definition at line 26 of file ResourceLoaderLessVarFileModule.php.
Bug: T219001
Bug: T232104
Change-Id: I7f133c10acca084239a158c63c08b71e709404c3
These have no matches in this repo: `@arrayof`, `@null`, `@boolean`,
`@bool`, `@integer`, `@int`, `@string`, `@str`, `@mixed`, `@public`.
Change-Id: If95ffb679df88656f059e8d94def8aa25459ccbe
Doxygen has native support for indexing of Markdown pages.
It basically parses them the same way it parses the uglier
methodology of creating a PHP file containing a the markdown
text in a large comment that would start with `@page` or `@mainpage`.
* http://doxygen.nl/manual/commands.html#cmdpage
* http://doxygen.nl/manual/commands.html#cmdmainpage
* http://doxygen.nl/manual/markdown.html#md_page_header
The internal reference name and page title (comparable to the string
passed to `@mainpage` or `@page`) are by default derived from the
file name (without suffix).
The internal reference name (for use in cross-page links) can also
be overidden with an `{#something}` annotation in the first heading.
When using the annotation `{#mainpage}` it changes the page type
from a regular `@page` to the `@mainpage`.
Change-Id: I0c25a49088825744773c4d87dde5688894b2004e
* File patterns - Keep only ".php" and ".inc". The other file types
either don't exist in this repo, or exist but have 0 parseable doc
blocks for Doxygen to find. Also remove README, it leads to various
pointless attempts for Doxygen to parse files by this name without
any documentable entity in them. Such as;
> mediawiki/includes/jobqueue/README:82: warning: Reached end of file
> while still inside a nested comment. Nesting level 1.
* Remove 'PERL_PATH'. This has been unused since Doxygen 1.8.0,
the last build on doc.wikimedia.org from Jenkins uses Doxygen 1.8.13.
As of Doxygen 1.8.16 a deprecation warning was also added,
https://github.com/doxygen/doxygen/commit/6d1535c.
Change-Id: I99bd80f9cf7bae8d37caf0b9325bd30a16020497
https://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_quiet
* To make the standard output in Jenkins more useful,
disable the verbose messages about "Loading file .." in between
all the errors.
* Remove obsolete config options XML_SCHEMA and XML_DTD that were
producing warnings. We weren't using these anyway (set to their default
blank value).
Change-Id: I6876cf4d783f7795a12d99623c8ce3717e9a51f5
Document the template's variables, and remove some unused XML generation
options that are obsolete in doxygen 1.8.9.
Change-Id: Ief9a03e7c63787e64b96adde24512aa86b77d78b
This annotations are not relevant for Doxygen.
Examples:
> parserTest.inc:320: warning: Found unknown command `\group'
> ActionTest.php:3: warning: Found unknown command `\covers'
> ActionTest.php:128: warning: Found unknown command `\dataProvider'
> ApiBlockTest.php:67: warning: Found unknown command `\expectedException'
> ApiBlockTest.php:68: warning: Found unknown command `\expectedExceptionMessage'
Change-Id: I1d2d617ee6c15d51943bec3563ea4ffd353baec4
This phpcs annotation is not relevant for Doxygen.
> Preprocessor_DOM.php:24: warning: Found unknown command `\codingStandardsIgnoreStart'
> Preprocessor_Hash.php:760: warning: Found unknown command `\codingStandardsIgnoreStart'
Change-Id: I91ea668486a87fff0193a3cccb97f96943d4bf33
Latest stable is v1.8.8, but Ubunu Trusty (which we now use on the
Jenkins slave that generates our documentation) ships doxygen v1.8.6.
Time to migrate away from 1.7.x stuff.
Warnings:
Tag `SYMBOL_CACHE_SIZE' at line 84 of file maintenance/Doxyfile has become obsolete.
Tag `SHOW_DIRECTORIES' at line 118 of file maintenance/Doxyfile has become obsolete.
Tag `HTML_ALIGN_MEMBERS' at line 226 of file maintenance/Doxyfile has become obsolete.
Tag `USE_INLINE_TREES' at line 253 of file maintenance/Doxyfile has become obsolete.
Regenerated with:
$ doxygen -u -s ./maintenance/Doxyfile
Which automatically added new configurations settings, removed
obsolete ones, migrated formatting to their new standard.
Change-Id: I372ea06c439762578cb4c68686344eb446925c04
The lookup cache size is exhausted again, bumping it from:
131072 entries - 2^(16+1)
to 262144 entries - 2^(16+2)
See previous bump for details:
432a0cbhttps://gerrit.wikimedia.org/r/69709
Change-Id: I9a15cce6f77745c4e913a562e8f1f43a4988c83d
dot supports generating multiple graphs in one run, that was not always
the case and Doxygen had a default of not using that feature. Given it
got introduced in dot 1.8.10 and Wikimedia CI server has 2.26.x, I guess
it is safe to enable this.
End result, is less shell out overhead.
Change-Id: Ia07b430bd1af608bbe9c10eecbe2df3e0b9c74fc
At the end of a run, doxygen emits a notice regarding the cache lookup
size being too small. This cache is used to find symbols given their
name which would speed up processing a bit.
The notice before this patch:
lookup cache used 65536/65536 hits=2258467 misses=112595
Note: based on cache misses the ideal setting for LOOKUP_CACHE_SIZE is 1
at the cost of higher memory usage.
And after:
lookup cache used 104632/131072 hits=2131285 misses=105434
That is 7% less miss, not that much but still. Note how the cache is
well filled (80%).
Change-Id: I0b97e8c5581a63c44a382891f8f1fc8d60975e80
The Wikimedia CI server runs doxygen 1.7.6.1, this patch sync our
configuration with that version.
TCL_SUBST and LOOKUP_CACHE_SIZE have been added.
IDL_PROPERTY_SUPPORT default value changed, unused by us though
Change-Id: Ic43d99c4675eb8f1772a72a9b9bfaf16057e19f1
In doxygen, code snippets (and possibly over places) have their
tabulations expanded to 8 spaces which is a bit too much. The TAB_SIZE
configuration parameter let us set the number of spaces, down to 4 which
makes code examples easier to read IMHO.
Change-Id: I62b417496f4e5ec70e80919c28747f1bd44a7bd6
Now based on Maintenance class.
Reinstate {{EXCLUDE}} which got removed by 8199984
This is roughly back compatible.
bug: 34436
Change-Id: Ic1a2b2c29718054ec740b2ffb90350af700a6a58
* @licence -> @license
* Protects inline HTML by using double quotes, our inline comments uses
elements such as <h1> or <firstnameLastname@gmail.com>
* Commands in lowercase (@TODO -> @todo, @NOTE -> @note)
* removes @abstract and @static since doxygen detects them from PHP
code.
* various undocumented function parameters
* typos in parameters declarations
Change-Id: I62ad6fc124c355bf31acc780b9614a59cf79a421
The default doxygen configuration file only accepts source files such
as php or python. Some of our documentation is in flat files which we
might want to include in our Doxygen inline documentation. The culprit
is that those document files needs to respect Doxygen syntax, i.e. the
text content need to be enclosed in a comment block such as:
/*!
\page page_title My Page Title
My awesome documentation
*/
Doyxgen 1.8 supports markdown syntax, we might want to switch to that
eventually.
Change-Id: I78a0ce36314b2a7b9f89395e3ae3902b17cf5038
When running mwdocgen.php outside of maintenance, the input filter was
not found. Giving the full path fix the issue.
Issue introduced by I4ead1bd1 / ab59fad.
Change-Id: I5e28209eba1afd24d60b2dc940b9f5dfb1b4f34c
