{"id":507,"date":"2012-09-24T22:26:22","date_gmt":"2012-09-24T22:26:22","guid":{"rendered":"http:\/\/blog.mozilla.org\/l10n\/?p=507"},"modified":"2012-09-24T22:26:22","modified_gmt":"2012-09-24T22:26:22","slug":"documenting-l20n-js","status":"publish","type":"post","link":"https:\/\/blog.mozilla.org\/l10n\/2012\/09\/24\/documenting-l20n-js\/","title":{"rendered":"Documenting L20n.js"},"content":{"rendered":"<p><em>L20n&#8217;s JS lib is getting test cases and better documentation to make the code easier to work with and understand.<\/em><\/p>\n<p>The JavaScript implementation of L20n is composed of 4 main components:<\/p>\n<ul>\n<li>context (stas), which handles resource loading, locale fallback and provides an easy pulic API for getting translated strings by identifiers,<\/li>\n<li>parser (gandalf), which parses the resources downloaded by the context into an AST,<\/li>\n<li>compiler (stas), which takes the AST and makes it into JavaScript objects which the context can call to get translated strings,<\/li>\n<li>and finally, HTML bindings (gandalf), which extend <code>HTMLDocument<\/code> with a default L20n context capable of automatically loading resources specified via <code>link<\/code> elements.<\/li>\n<\/ul>\n<p>At this point, we\u2019re almost feature frozen for all of these four components. We\u2019re fixing bugs and making sure the public API is consistent and understandable.<\/p>\n<p>Last two weeks saw us working hard on the context part. We finished a major code refactoring and introduced a robust locale fallback, which I\u2019ll blog about in a future post.<\/p>\n<h2 id=\"testing_with_mocha\">Testing with Mocha<\/h2>\n<p>Another important improvement introduced recently was the addition of a full-featured testing framework, <a href=\"http:\/\/visionmedia.github.com\/mocha\/\">Mocha<\/a>. We\u2019ve written over 200 <a href=\"https:\/\/github.com\/stasm\/l20n.js\/tree\/master\/tests\/compiler\">test cases for the compiler<\/a> and currently we\u2019re creating more tests for other components. As an nice bonus, Mocha also gives us beautiful <a href=\"http:\/\/l20n.github.com\/l20n.js\/coverage.html#overview\">test coverage reports<\/a>.<\/p>\n<p>Mocha is based on node.js, so we had to make a few small modifications to the codebase in order to support it. For example, we make use of <a href=\"https:\/\/github.com\/driverdan\/node-XMLHttpRequest\">node-XMLHttpRequest<\/a> to mimic the XHR interface available in the browser.<\/p>\n<h2 id=\"project_page_on_github\">Project page on GitHub<\/h2>\n<p>We created a GitHub page to serve as the entry point for all of the docs that we\u2019re writing. Check it out at <a href=\"http:\/\/l20n.github.com\/l20n.js\/\">l20n.github.com\/l20n.js<\/a>.<\/p>\n<p>We use excellent <a href=\"https:\/\/github.com\/jashkenas\/docco\">Docco<\/a> to generate documentation from the comments in the code. See the <a href=\"http:\/\/l20n.github.com\/l20n.js\/lib\/compiler.html\">compiler docs<\/a> for an example.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>L20n&#8217;s JS lib is getting test cases and better documentation to make the code easier to work with and understand. The JavaScript implementation of L20n is composed of 4 main &hellip; <a class=\"go\" href=\"https:\/\/blog.mozilla.org\/l10n\/2012\/09\/24\/documenting-l20n-js\/\">Read more<\/a><\/p>\n","protected":false},"author":104,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[503],"tags":[],"_links":{"self":[{"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/posts\/507"}],"collection":[{"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/users\/104"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/comments?post=507"}],"version-history":[{"count":0,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/posts\/507\/revisions"}],"wp:attachment":[{"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/media?parent=507"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/categories?post=507"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/tags?post=507"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}