Validator 0.4.3:introducing auto-documentation

It’s been a while since the previous release of Validator, but this minor update includes some cool new functionality.

As I was creating the SubPageList extension and it’s documentation (at 27c3!), it occurred to me that to document the usage of the <subpages /> parser hook, all the info I needed was already available via Validator. Since there was no way to get this info out in a meaningful way, I decided to create a new parser hook just for this purpose. It’s titled “describe” and describes one or more parser hooks implemented using the ParserHook class provided by Validator. This description includes a short text about the parser hooks functionality, a table with it’s parameters and their meta-data, syntax examples, a list of aliases (if any) and more. It’s possible to get the description in wikitext, as opposed directly in the page, so you can copy it, and use it (or parts of it) somewhere else. By default it’ll list all parser hooks it knows about directly in the page. An example can be seen here.

Some documentation (for the coordinates parser function) generated using the describe parser hook

Many more not yet implemented features that make use of the parameter handling framework that is Validator can be imagined. One I might implement in the near future is linking to a special page that generates a description of how to use a certain parser hook based on something the user is doing wrong, and link to that from error messages. This can be done easily by building on top of the already existing error message system and the describe parser hook 🙂

I think Validator adds a lot of Value when creating parser hooks, and other parameter handling objects. The main problem currently is that when using it’s features in an extension, this extension obviously becomes dependent on Validator. From a technical perspective this does not really matter, but it complicates installation for users (especially since MediaWiki lacks any sort of extension management facilities). I therefore hope to get Validators functionality into MediaWiki core, or at least in the default MediaWiki distribution. I’m rather sceptical to if I can make this happen as a non core-developer, but if I succeed, it would be a great advantage for extension (and core) development, so it’s definitely worth a try.

SubPageList 0.1 comes bundled with an alpha version of Validator 0.4.3, containing most of the new functionality. Maps and Semantic Maps will come bundled with it (or a newer version) on their next release.


2 thoughts on “Validator 0.4.3:introducing auto-documentation”

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.