{"id":343,"date":"2009-07-20T21:09:04","date_gmt":"2009-07-21T05:09:04","guid":{"rendered":"http:\/\/www.visophyte.org\/blog\/?p=343"},"modified":"2009-07-21T08:07:33","modified_gmt":"2009-07-21T16:07:33","slug":"doccelerator-javascript-documentation-via-jshydra-into-couchdb-with-an-ajax-ui","status":"publish","type":"post","link":"https:\/\/www.visophyte.org\/blog\/2009\/07\/20\/doccelerator-javascript-documentation-via-jshydra-into-couchdb-with-an-ajax-ui\/","title":{"rendered":"Doccelerator: JavaScript documentation via JSHydra into CouchDB with an AJAX UI"},"content":{"rendered":"<p><a href=\"http:\/\/www.visophyte.org\/blog\/wp-content\/uploads\/2009\/07\/doccelerator-1.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-thumbnail wp-image-346\" title=\"doccelerator-1\" src=\"http:\/\/www.visophyte.org\/blog\/wp-content\/uploads\/2009\/07\/doccelerator-1-600x371.png\" alt=\"doccelerator-1\" width=\"600\" height=\"371\" srcset=\"https:\/\/www.visophyte.org\/blog\/wp-content\/uploads\/2009\/07\/doccelerator-1-600x371.png 600w, https:\/\/www.visophyte.org\/blog\/wp-content\/uploads\/2009\/07\/doccelerator-1-300x185.png 300w, https:\/\/www.visophyte.org\/blog\/wp-content\/uploads\/2009\/07\/doccelerator-1-1024x633.png 1024w, https:\/\/www.visophyte.org\/blog\/wp-content\/uploads\/2009\/07\/doccelerator-1.png 1321w\" sizes=\"auto, (max-width: 600px) 100vw, 600px\" \/><\/a><\/p>\n<p>About the name.\u00a0 <a href=\"http:\/\/ascher.ca\/blog\/\">David Ascher<\/a> picked it.\u00a0 My choice was flamboydoc in recognition of my love of <a href=\"http:\/\/www.emacswiki.org\/emacs\/AngryFruitSalad\">angry fruit salad<\/a> color themes and because every remotely sane name has already been used by the 10 million other documentation tools out there.\u00a0 Regrettably not only have we lost the excellent name, but the color scheme is at best mildly irritated at this point.<\/p>\n<p>So why yet another JavaScript documentation tool:<\/p>\n<ul>\n<li>JavaScript 1.8 support.\u00a0 <a href=\"http:\/\/quetzalcoatal.blogspot.com\/2009\/01\/jshydra.html\">JSHydra<\/a> (thanks <a href=\"http:\/\/quetzalcoatal.blogspot.com\/\">jcranmer<\/a>!) is built on spidermonkey.\u00a0 In terms of existing JS documentation tools out there, they can be briefly lumped into &#8220;doesn&#8217;t even both attempting to parse JavaScript&#8221; and &#8220;parses it to some degree, but gets really confused by JavaScript 1.8 syntax&#8221;.\u00a0 By having the parser be the parser of our\u00a0 JS engine, parsing success is guaranteed.\u00a0 And non-parsing tools tend to require too much hand labeling to be practical.<\/li>\n<li>Docceleterator is not intended to be <em>just<\/em> a documentation tool.\u00a0 While JSHydra is still in its infancy, it promises the ability to extract information from function bodies.\u00a0 Its namesake, <a href=\"https:\/\/developer.mozilla.org\/en\/Dehydra\">Dehydra<\/a>, is a static analysis tool for C++ and has already given us <a href=\"http:\/\/vocamus.net\/dave\/?p=557\">great things<\/a> (dxr, also in its infancy).<\/li>\n<\/ul>\n<p><a href=\"http:\/\/www.visophyte.org\/blog\/wp-content\/uploads\/2009\/07\/doccelerator-comment.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone size-thumbnail wp-image-347\" title=\"doccelerator-comment\" src=\"http:\/\/www.visophyte.org\/blog\/wp-content\/uploads\/2009\/07\/doccelerator-comment-600x202.png\" alt=\"doccelerator-comment\" width=\"600\" height=\"202\" srcset=\"https:\/\/www.visophyte.org\/blog\/wp-content\/uploads\/2009\/07\/doccelerator-comment-600x202.png 600w, https:\/\/www.visophyte.org\/blog\/wp-content\/uploads\/2009\/07\/doccelerator-comment-300x101.png 300w, https:\/\/www.visophyte.org\/blog\/wp-content\/uploads\/2009\/07\/doccelerator-comment-1024x345.png 1024w, https:\/\/www.visophyte.org\/blog\/wp-content\/uploads\/2009\/07\/doccelerator-comment.png 1053w\" sizes=\"auto, (max-width: 600px) 100vw, 600px\" \/><\/a><\/p>\n<ul>\n<li>Support community API docs contributions without forking the API docs or requiring source patches.\u00a0 <a href=\"https:\/\/developer.mozilla.org\/\">DevMo<\/a> is a great place for documentation, but it is an iffy place for doxygen-style API docs.\u00a0 Short of an exceedingly elaborate tool that round-trips doxygen\/JSDoc comments to the wiki and user modifications back again, the documentation is bound to diverge.\u00a0 By supporting comments directly on the semantic objects themselves[1], we eliminate having to try and determine what a given wiki change corresponds to.\u00a0 (This would be annoying even if you could force the wiki users to obey a strict formatting pattern.)\u00a0 This enables automatic patch generation, etc.<\/li>\n<li>Mashable.\u00a0 You post the JavaScript source file to a server running the doccelerator parser.\u00a0 You get back a JSON set of documents.\u00a0 You post those into a <a href=\"http:\/\/couchdb.org\/\">CouchDB<\/a> couch.\u00a0 The UI is a <a href=\"http:\/\/github.com\/jchris\/couchapp\/tree\/master\">CouchApp<\/a>; you can modify it.\u00a0 Don&#8217;t like the UI, just want a service?\u00a0 You can query the couch for things and get back JSON documents.\u00a0 Want custom (CouchDB) views but are not in control of a documentation couch?\u00a0 Replicate the couch to your own local couch and add some views.<\/li>\n<li>Able to leverage data from dehydra\/dxr.\u00a0 Mozilla JS code lives in a world of XPCOM objects and their XPIDL-defined interfaces.\u00a0 We want the JS documentation to be able to interact with that world.\u00a0 Obviously, this raises some issues of where the boundary lies between dxr and Doccelerator.\u00a0 I don&#8217;t think it matters at this point; we just need internal and API documentation for Thunderbird 3 now-ish.<\/li>\n<li>A more &#8216;dynamic&#8217; UI.\u00a0 The UI is inspired by <a href=\"http:\/\/www.tiddlywiki.com\/\">TiddlyWiki<\/a>&#8216;s interface where all wiki &#8220;pages&#8221; open in the same document.\u00a0 I often find myself only caring about a few methods of a class at any given time.\u00a0 Documentation is generally either organized in monolithic pages or single pages per function.\u00a0 Either way, I tend to end up with a separate tab for each thing of interest.\u00a0 This usually ends in both confusion and way too many tabs.<\/li>\n<\/ul>\n<p>1: Right now I only support commenting at the documentation display granularity which means you cannot comment on arguments individually, just the function\/method\/class\/etc.<\/p>\n<p>Example links which will eventually die because I&#8217;m not guaranteeing this couch instance will stay up forever:<\/p>\n<ul>\n<li><a href=\"http:\/\/clicky.visophyte.org\/examples\/live\/doccelerator\/_design\/doccelerator\/index.html#f=comm-central\/mail\/base\/content\/folderDisplay.js&amp;t=FolderDisplayWidget\">Live version of the first screen shot of folderDisplay.js and FolderDisplayWidget<\/a><\/li>\n<li><a href=\"http:\/\/clicky.visophyte.org\/examples\/live\/doccelerator\/_design\/doccelerator\/index.html#n=FTBO_stubOutAttributes\">Live version of the second screen shot of comments on FTBO_stubOutAttributes.\u00a0 Feel free to add your own.<\/a><\/li>\n<li><a href=\"http:\/\/clicky.visophyte.org\/examples\/live\/doccelerator\/_design\/doccelerator\/index.html\">Live version with nothing up.\u00a0 Click on some files, explore!<\/a><\/li>\n<\/ul>\n<p>The hg repo is <a href=\"http:\/\/hg.mozilla.org\/users\/bugmail_asutherland.org\/doccelerator\/\">here<\/a>.\u00a0 I tried to code the JS against the 1.5 standard and generally be cross-browser compatible, but I know at least Konqueror seems to get upset when it comes time to post (modified) comments.\u00a0 I&#8217;m not sure what&#8217;s up with that.<\/p>\n<p>Exciting potential taglines:<\/p>\n<ul>\n<li>Doccelerator: Documentation from the future, because the documentation was doccelerated past the speed of light, and we all know how that turns out.<\/li>\n<li>Doccelerator: It sounds like an extra pedal for your car and it&#8217;s just as easy to use&#8230; unless we&#8217;re talking about the clutch.<\/li>\n<li>Doccelerator: Thankfully the name doesn&#8217;t demand confusingly named classes in the service of a stretched metaphor.\u00a0 That&#8217;s good, right?<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"<p>About the name.\u00a0 David Ascher picked it.\u00a0 My choice was flamboydoc in recognition of my love of angry fruit salad color themes and because every remotely sane name has already been used by the 10 million other documentation tools out &hellip; <a href=\"https:\/\/www.visophyte.org\/blog\/2009\/07\/20\/doccelerator-javascript-documentation-via-jshydra-into-couchdb-with-an-ajax-ui\/\">Continue reading <span class=\"meta-nav\">&rarr;<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"inline_featured_image":false,"footnotes":""},"categories":[15,1],"tags":[130,64,65,66],"class_list":["post-343","post","type-post","status-publish","format-standard","hentry","category-couchdb","category-uncategorized","tag-couchdb","tag-doccelerator","tag-docs","tag-jshydra"],"_links":{"self":[{"href":"https:\/\/www.visophyte.org\/blog\/wp-json\/wp\/v2\/posts\/343","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.visophyte.org\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.visophyte.org\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.visophyte.org\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.visophyte.org\/blog\/wp-json\/wp\/v2\/comments?post=343"}],"version-history":[{"count":4,"href":"https:\/\/www.visophyte.org\/blog\/wp-json\/wp\/v2\/posts\/343\/revisions"}],"predecessor-version":[{"id":350,"href":"https:\/\/www.visophyte.org\/blog\/wp-json\/wp\/v2\/posts\/343\/revisions\/350"}],"wp:attachment":[{"href":"https:\/\/www.visophyte.org\/blog\/wp-json\/wp\/v2\/media?parent=343"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.visophyte.org\/blog\/wp-json\/wp\/v2\/categories?post=343"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.visophyte.org\/blog\/wp-json\/wp\/v2\/tags?post=343"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}