{"id":247,"date":"2008-09-30T17:52:49","date_gmt":"2008-09-30T21:52:49","guid":{"rendered":"http:\/\/benjamin.smedbergs.us\/blog\/?p=247"},"modified":"2008-09-30T20:28:00","modified_gmt":"2008-10-01T00:28:00","slug":"generating-documentation-with-dehydra","status":"publish","type":"post","link":"http:\/\/benjamin.smedbergs.us\/blog\/2008-09-30\/generating-documentation-with-dehydra\/","title":{"rendered":"Generating Documentation With Dehydra"},"content":{"rendered":"<p>One of the common complaints about the Mozilla string code is that it&#8217;s very difficult to know what methods are available on a given class. Reading the code is very difficult because it&#8217;s hidden behind a complex set of #defines, it&#8217;s parameterized for both narrow and wide strings, and because we have a deep and complex string hierarchy. The Mozilla Developer Center has a string guide, but not any useful reference documentation.<\/p>\n<p>With a little hand-holding, static analysis tools can produce very useful reference documentation, which other tools simply cannot make. For example, because a static analysis tool knows the accessibility of methods, you can create a reference document that contains only the public API of a class. I spent parts of yesterday and today tweaking a <a href=\"http:\/\/developer.mozilla.org\/En\/Dehydra\">Dehydra<\/a> script to produce a string reference. I&#8217;m working with Eric Shepherd to figure out the best way to automatically upload the data to the Mozilla Developer Center, but I wanted to post a sample for comment. This is the public API of nsACString:<\/p>\n<p><iframe width=\"100%\" src='http:\/\/benjamin.smedbergs.us\/blog\/wp-content\/uploads\/2008\/09\/nsacstring_internal-fixed.html' height=\"300\"><a href=\"http:\/\/benjamin.smedbergs.us\/blog\/wp-content\/uploads\/2008\/09\/nsacstring_internal-fixed.html\">Reference for nsACString (internal version)<\/a><\/iframe><\/p>\n<p>I am trying to keep the format of this document similar to the <a href=\"http:\/\/developer.mozilla.org\/Project:En\/Sample_interface_document\">format we use for interfaces<\/a> on MDC. It&#8217;s a bit challenging, because C++ classes have overloaded method names and frequently have many methods. In the method summary, I have grouped together all the methods with the same name.<\/p>\n<p>Once the output and format are tweaked, I can actually hook the entire generation and upload process to a makefile target, and either run it on my local machine or hook it up to a buildbot. I used E4X to do the actual XML generation. It was a learning experience&#8230; I don&#8217;t think I&#8217;m a fan. I want Genshi for JavaScript. Making conditional constructs in E4X is slightly ugly, and making looping constructs is really painful: my kingdom for an XML generator so that I don&#8217;t have to loop and append to an XMLList.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>One of the common complaints about the Mozilla string code is that it&#8217;s very difficult to know what methods are available on a given class. Reading the code is very difficult because it&#8217;s hidden behind a complex set of #defines, it&#8217;s parameterized for both narrow and wide strings, and because we have a deep and [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2,6],"tags":[57,127,157,38],"class_list":["post-247","post","type-post","status-publish","format-standard","hentry","category-mozilla","category-untagged","tag-dehydra","tag-doxygen","tag-reference","tag-xpcom"],"_links":{"self":[{"href":"http:\/\/benjamin.smedbergs.us\/blog\/wp-json\/wp\/v2\/posts\/247","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/benjamin.smedbergs.us\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/benjamin.smedbergs.us\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/benjamin.smedbergs.us\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/benjamin.smedbergs.us\/blog\/wp-json\/wp\/v2\/comments?post=247"}],"version-history":[{"count":0,"href":"http:\/\/benjamin.smedbergs.us\/blog\/wp-json\/wp\/v2\/posts\/247\/revisions"}],"wp:attachment":[{"href":"http:\/\/benjamin.smedbergs.us\/blog\/wp-json\/wp\/v2\/media?parent=247"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/benjamin.smedbergs.us\/blog\/wp-json\/wp\/v2\/categories?post=247"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/benjamin.smedbergs.us\/blog\/wp-json\/wp\/v2\/tags?post=247"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}