On Fri, Mar 22, 2013 at 9:43 AM, Daniel Friesen <[email protected]>wrote:
> Right now a lot of our links to generated documentation on php classes are > manually copied. > > One of the reasons for this seems to be how badly Doxygen handles the > anchors to sections on individual methods. > Instead of simply using the method name it generates a md5 hash of a > signature that is impossible to know simply with a class and method name. > Meaning we can't simply have a template to link to documentation. > > However Doxygen exports a tagfile that includes a list of classes, their > methods, and the anchors used for their links. > > This is currently at: (*warning* large file) > https://doc.wikimedia.org/**mediawiki-core/master/php/**html/tagfile.xml<https://doc.wikimedia.org/mediawiki-core/master/php/html/tagfile.xml> > > What does everyone think of making it so that when Jenkins generates this > documentation. It processes the tagfile, splits it up and converts it into > multiple lua tables, then uses the API to update a Module: page on > mediawiki.org. > > This way templates can have some Lua code that uses that data to create > links with something like: > > local classes = mw.loadData( 'DoxygenTags mediawiki-core class' ) > ... > > function p.methodLink(className, methodName) > local class = classes[className] > ... > local method = members.function[methodName] > ... > return "https://doc.wikimedia.org/**mediawiki-core/master/php/** > html/ <https://doc.wikimedia.org/mediawiki-core/master/php/html/>" + > method.anchorfile + "#" + method.anchor > end > > ... > I would go further and suggest a way to integrate code comments into manual pages at mediawiki.org, so that we could have good documentation in both code and mw.org, without needing to sync it manually. For example, the detailed description of api.php found at https://doc.wikimedia.org/mediawiki-core/master/php/html/api_8php.html#detailscould be integrated into https://www.mediawiki.org/wiki/Manual:api.php Similarly, the contents of README files and the docs folder should be integratable into mw.org. If what Daniel suggests is feasible, I assume this also is, and imo would greatly improve the availability and quality of both in-wiki and code documentation. --Waldir _______________________________________________ Wikitech-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikitech-l
