Hello,
As part of the documentation of mediawiki, I am willing to document the code. I am testing phpdocumentator ( http://www.phpdoc.org/ ).
It works by using comments in the code that looks like:
/** * Method to return an articleID * @private */ function getArticleID () { ... }
You can get an output example at : http://www.twenkill.net/mwdoc/ (site available only when I am online).
Are we willing to flood our code with such comments ? I personally think it will help new developpers to come help us and let older developpers to better understand the whole software.
cheers,
Timwi-
Ashar Voultoiz wrote:
Are we willing to flood our code with such comments ? I personally think it will help new developpers to come help us and let older developpers to better understand the whole software.
I, for one, support this movement.
It's certainly a good start. However, function headers are only one part -- if a function goes over many pages, individual parts still have to be documented properly, which in many cases they currently are not. I would especially like to make it a requirement that any new option in DefaultSettings.php has to be documented properly, or it will not be accepted. Often it is not trivial for others to figure out what a particular option does.
Eventually, I think all the administrative options should be accessible through a web interface, like they are with phpBB etc. For that, we really need good documentation of what they do. Similarly, the people writing the Administrator's Guide on Meta will go through the configuration file. When they see something like
$wgEnableSoap = false; # Enable SOAP interface. Off by default
the comment doesn't really tell them anything the code didn't already. What is the SOAP interface and what does it do? That needs to be documented beyond CVS comments. In comparison, my comment for the ExtraNamespace feature was:
# Additional namespaces. If the namespaces defined in Language.php and # Namespace.php are insufficient, you can create new ones here, for # example, to import Help files in other languages. # PLEASE NOTE: Once you delete a namespace, the pages in that namespace # will no longer be accessible. If you rename it, then you can access them # through the new namespace name. # # Custom namespaces should start at 100.
Granted, the actual option is more complex (an array rather than a boolean). Still, we need to explain for each option exactly what it does. When you have a good source code comment, you can copy and paste it into the CVS summary, or you can say "see diff" in the summary.
We have to build our documentation up in layers, and our code is the most basic layer. Everything else depends on it being properly commented.
We probably also should separate options which can have undesirable effects post-installation (e.g. changing $wgLanguageCode requires rebuilding all messages) from those which can be changed at any time without problems.
We have a basic dev policy at http://meta.wikimedia.org/wiki/Development_policy
Maybe that can be fleshed out a bit more and sent to anyone who applies for CVS access.
Regards,
Erik
Ashar Voultoiz wrote:
Hello,
As part of the documentation of mediawiki, I am willing to document the code. I am testing phpdocumentator ( http://www.phpdoc.org/ ).
It works by using comments in the code that looks like:
/**
- Method to return an articleID
- @private
*/ function getArticleID () { ... }
You can get an output example at : http://www.twenkill.net/mwdoc/ (site available only when I am online).
Are we willing to flood our code with such comments ? I personally think it will help new developpers to come help us and let older developpers to better understand the whole software.
Hello,
I finished the phpdocumentor comments skeleton. Just enough to get something to start with. This is only for HEAD version, I am not going to backport it to 1_3.
The lastest documentation I have build is available at : http://wikipedia.sourceforge.net/mwdoc/
I splitted Maintenance, SpecialPage and Skins in their own subpackages. That ease reading a bit.
Error report is at : http://wikipedia.sourceforge.net/mwdoc/errors.html
Please have a look at this documentation, use it AND document code. I will have a look at sourceforge crontab to possibly update the doc once a day or so.
wikitech-l@lists.wikimedia.org