We still use doxygen to generate our php documentation. But let's be honest. It's terrible...
As we have further improved our documentation quality and consistency, our coding style etc, CI of our code, our generated documentation has been rather neglected so far, and none more than our MediaWiki Core documentation.
Doxygen is ancient
- Has a terrible reader experience in the default skin
- Doesn't mark deprecated functions, in the method overview, since etc.
- Search function is not too bright. Search for OutputPage, now try to reach the OutputPage class result... (I don't care about all the methods inside OutputPage)
We should consider alternate options like:
- Sami: Symfony example
- Apigen: AWS example
- PHPdox: phpdoc example
- phpDocumentor: Example
- What does Facebook use ? :)
- Fix up doxygen to be better.
Skills required: basic knowledge of scripting and or php
Actions:
- Check out the mediawiki codebase using git
- Briefly familiarize yourself with how MediaWiki API documentation is currently being generated.
- Try to use one of the other tools to generate documentation from the same codebase
- See if you can use the options of the documentation system, to create equal or better results than the current doxygen documentation. You might have to make some changes to the current documentation in the code due to difference with doxygen, but pick no more than 3 classes and include in your outcome, which 3 classes you made changes to.
Outcome:
- A script or set of commandline options to generate documentation using the the alternative documentation generator
- A zip bundle of the generated documentation