Page MenuHomePhabricator

Improve the generated PHPdoc (by considering alternatives to Doxygen?)
Open, LowPublic

Description

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:

Skills required: basic knowledge of scripting and or php
Actions:

  1. Check out the mediawiki codebase using git
  2. Briefly familiarize yourself with how MediaWiki API documentation is currently being generated.
  3. Try to use one of the other tools to generate documentation from the same codebase
  4. 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:

  1. A script or set of commandline options to generate documentation using the the alternative documentation generator
  2. A zip bundle of the generated documentation

Event Timeline

TheDJ created this task.Nov 3 2015, 9:07 AM
TheDJ raised the priority of this task from to Needs Triage.
TheDJ updated the task description. (Show Details)
TheDJ added a project: MediaWiki-Documentation.
TheDJ added a subscriber: TheDJ.
Restricted Application added a project: Documentation. · View Herald TranscriptNov 3 2015, 9:07 AM
Restricted Application added a subscriber: Aklapper. · View Herald Transcript

Might be nice for a Google-Code-In student to experiment with this ? I might be able to mentor that.

TheDJ set Security to None.Nov 3 2015, 3:30 PM
TheDJ added a subscriber: Spage.
TheDJ updated the task description. (Show Details)Nov 3 2015, 3:34 PM

I will mentor this in #GCI2015

Restricted Application added a subscriber: StudiesWorld. · View Herald TranscriptNov 16 2015, 5:54 PM

Might be nice for a Google-Code-In student to experiment with this ?

Could someone first edit the task description to make it clearer which skills the GCI student should have and which outcome would be expected from the GCI student?
@TheDJ: Still up for (co-)mentoring?

Might be nice for a Google-Code-In student to experiment with this ?

Could someone first edit the task description to make it clearer which skills the GCI student should have and which outcome would be expected from the GCI student?
@TheDJ: Still up for (co-)mentoring?

TheDJ added a comment.Dec 2 2015, 12:06 PM

I'm co-mentoring this.

TheDJ updated the task description. (Show Details)Dec 2 2015, 12:13 PM
TheDJ updated the task description. (Show Details)

Will the result of this be an RFC to replace doxygen, or just a proof of concept?

I'm not crazy about Doxygen, but it draws class diagrams. None of those alternatives do.

The replacement needs to support the @ syntax we use. It seems (ack --php '^\s*\* .*\\[a-z]' ) that MediaWiki PHP rarely uses doxygen's \ syntax; one exception I'm aware of is includes/filebackend/README.

It would be nice if the replacement supported .md markdown files. Doxygen does, though we have yet to take advantage of this in core.

Any replacement needs to have stable internal URLs so that all the templates that generate doxygen links ({{Class doclink}}, {{MW file}}, and several others in Category:External link templates) can link to pages in the new system.

Good luck!

@TheDJ: For GCI, this task would still require some clarification which skills the GCI student should have, which work to perform, and which outcome would be expected from the GCI student. Could you clarify?

TheDJ updated the task description. (Show Details)Dec 7 2015, 12:02 AM
TheDJ added a comment.Dec 7 2015, 12:04 AM

Better this way ?
We could split into multiple tasks for different doc. generation libraries ?

Better this way ?

Yes! Thank you! Happy to see potential "Research" GCI tasks!

We could split into multiple tasks for different doc. generation libraries ?

Sounds good to me! Shall I try to create them on the GCI site (we should probably ask students to document their findings on a wikipage which is a subpage of their user wikipage on mediawiki.org? Or create an empty wikipage with sections for each library that the student should fill; any ideas for potentially given subsections to structure results?), or do you want to give this a shot?

Qgil triaged this task as Low priority.Jan 12 2016, 7:32 AM
Qgil added a subscriber: Qgil.
Qgil added a comment.Jan 27 2016, 7:57 AM

Google-Code-In-2015 is now completed and I wonder whether this task has any chances to be dealt with during this quarter. I'm asking because I'm going through our long column form this quarter at the Developer-Advocacy workboard.

Aklapper renamed this task from Improve the generated PHPdoc to Improve the generated PHPdoc (by considering alternatives to Doxygen?).Feb 11 2016, 5:49 PM
Seb35 added a subscriber: Seb35.Nov 28 2016, 8:12 AM
Ricordisamoa updated the task description. (Show Details)
Ricordisamoa added a subscriber: Ricordisamoa.
Restricted Application added a subscriber: jhsoby-WMNO. · View Herald TranscriptAug 20 2018, 8:41 PM